disko: declarative disk partitioning for NixOS, and the upgrade path that is not documented

The manual step disko removes from a NixOS install

NixOS describes the system as code, but the README is blunt about the exception: during installation, disk partitioning and formatting stay manual. disko takes the layout you would normally type at parted, mkfs and mount and expresses it in Nix instead. The README names three cases where that matters: unattended installations, re-installation after a system crash, and setting up more than one identical server. The audience is therefore NixOS operators who already keep their system configuration in a repository and want the disk to live there too, not people looking for a general-purpose partitioning tool with a graphical front end. The configuration is the artifact. You can keep it, reuse it for other installations, or apply it during a rebuild, which is the part a shell script cannot give you.

How a disko configuration becomes partitions

The mechanism is a NixOS module. Under disko.devices you declare disks, and each disk has a device path, a type, and content. Content nests: a disk contains a partition table of type gpt or an MBR variant, the table contains partitions, and a partition contains a filesystem, an LVM volume, a LUKS container or a RAID member. The README lists GPT, MBR and mixed layouts, LVM, mdadm and LUKS as partition tools, and ext4, btrfs, ZFS, bcachefs and tmpfs as filesystems, with recursive layouts supported. The mountpoint attribute on the innermost content is what ties the tree back to the running system: disko formats the filesystem and mounts it where you said. The repository ships example/luks-lvm.nix, example/luks-btrfs-raid.nix, example/lvm-thin.nix and example/mdadm-raid0.nix, which is the practical way to learn the nesting order, since the README's own sample stops at a single GPT disk with an ESP and one ext4 root.

Installing disko and partitioning a first disk

There is no installation step. The README states that disko can be run directly from the nix-community repository, so the flake reference is the entry point. The sample configuration below is the README's own: one disk at /dev/sda, a GPT table, a 500M EFI system partition formatted vfat and mounted at /boot, and the rest of the disk as ext4 at /. Save it as /tmp/disk-config.nix, then run the documented command in the second block. The mode string is a comma-separated list, and destroy,format,mount means exactly what it says: existing partitions on the named disk are removed first. The README does not document a dry-run flag, so read the mode string as the safety mechanism. For a remote machine, the README points at nixos-anywhere instead, and for a combined partition-and-install step it points at the disko-install tool. The repository also carries example/luks-fido2.nix and example/luks-interactive-login.nix if you want encryption, and docs/disko-images.md for building disk images rather than touching a live device.

{
  disko.devices = {
    disk = {
      my-disk = {
        device = "/dev/sda";
        type = "disk";
        content = {
          type = "gpt";
          partitions = {
            ESP = {
              type = "EF00";
              size = "500M";
              content = {
                type = "filesystem";
                format = "vfat";
                mountpoint = "/boot";
                mountOptions = [ "umask=0077" ];
              };
            };
            root = {
              size = "100%";
              content = {
                type = "filesystem";
                format = "ext4";
                mountpoint = "/";
              };
            };
          };
        };
      };
    };
  };
}

With that file saved, the README gives this invocation to partition, format and mount the disk:

sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko/latest -- --mode destroy,format,mount /tmp/disk-config.nix

Modes, upgrades and the missing rollback story

Two things stand out once you move past the quickstart. The first is that disko is destructive by design and the documentation offers no rollback. The README mentions upgrading from an older version only by pointing at the How To guide; it does not describe how to migrate a disk that already holds data to a new layout, and the mode strings themselves are the only description of what happens to existing partitions. The second is version churn in the command line. The README's example uses the modern flake invocation with an explicit experimental-features flag, while the repository still contains cli.nix and install-cli.nix alongside the disko and disko-install scripts, and the How To guide exists partly to cover upgrading from an older version. If you built automation against an earlier release, pin the flake input rather than following latest. Releases are infrequent (v1.13.0 in January 2026, v1.12.0 in May 2025), so the cost of pinning is low and the cost of a surprise flag change during an unattended install is not.

When disko is the wrong tool

disko is not a partition manager for a running system you intend to keep. It has no concept of shrinking a filesystem to make room, and nothing in the README suggests it can preserve data across a layout change. If your task is resizing a root partition on a production host, use the usual tools interactively. It is also a poor fit outside NixOS: the README does describe using disko without NixOS, but the configuration language is Nix and the value comes from the layout living next to the rest of your system definition. A team that has not adopted Nix gains little from writing a Nix file to call parted once. Finally, disko describes disks, not machines: it will not decide your bootloader, your swap policy or your encryption key handling, and the examples that do cover those (luks-fido2, luks-interactive-login) are starting points rather than defaults.

nixpart and nixos-anywhere: what sits around disko

The README acknowledges NixOS/nixpart as the conceptual ancestor of the project, so the closest comparison is the tool disko replaced rather than a competitor. The difference in approach is scope: nixpart also aimed at declarative partitioning, while disko's README positions it as a module that runs from a flake and pairs with nixos-anywhere, which the README says uses disko to carry out a fully automated remote install of NixOS. That pairing is the real alternative to consider. If you only need to install NixOS on a remote machine, nixos-anywhere is the interface you will actually type, and disko is the layer underneath that you configure. If you are installing locally from an installer image, the README's quickstart path is the shorter route. Choosing between them is not a matter of one being better; it is whether the disk layout is the thing you want to own, or a detail you are happy to let another tool drive.

Licence, maintenance and what an upgrade costs you

disko is MIT licensed, which the README states plainly and which places few obligations on internal or commercial use; that is a description of the licence text, not legal advice, and anything you redistribute should be checked against the full text in LICENSE. Maintenance is visible in the repository rather than in a support contract: the last push to master was on 2026-09-21, and the most recent tagged release is v1.13.0 from 2026-01-20, with v1.12.0 in May 2025 and v1.11.0 in January 2025. The gap between tags and commits is worth noting if you track master, because the CLI and the module can move between releases. Upgrading therefore has two costs: re-reading the reference guide for flag changes, and re-testing your layout, ideally on a virtual machine or a disk image built through docs/disko-images.md, before it runs against hardware you care about.

Editorial conclusion

Adopt disko if you reinstall NixOS often, build identical servers, or drive remote installs through nixos-anywhere, because the layout becomes a file you review and version. Do not point it at a machine whose data you have not backed up: the documented destroy,format,mount mode removes partitions before it creates them. Before trusting it on real hardware, verify three things in the documentation: whether your release still supports the older CLI flags, what the mode strings do to the disks you name, and whether your own layout is covered by the examples in the repository.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nix-community/disko on GitHub
4. README
5. Releases