NixOS is a Linux distribution where everything is described as code, with one exception: during installation, the disk partitioning and formatting are manual steps. disko aims to correct this.

You write a declarative device tree — disks, partition tables, RAID sets, volume groups, pools and filesystems — and disko turns it into three shell scripts: destroy, format and mount. The same declaration is also fed back into NixOS as fileSystems, swapDevices and boot.initrd.luks.devices, so you never hand-write a hardware-configuration.nix filesystem section again.

A disko config is a tree of nested content. Every node has a type, and most nodes have a content attribute holding the next node down. The chain always ends in something mountable.

Two kinds of nodes exist:

Nodes that span multiple disks (lvm_vg, zpool, mdadm, bcachefs_filesystems) are declared as entry points and referenced by name from the partitions that feed them. That is why lvm_pv only carries vg = "pool" — the actual volume group lives at the top level.

Note that gpt and table are only valid as device content (disk, mdadm), not inside a partition — a partition can't hold another partition table.

The /latest in the URL pins to the latest tagged release rather than master.

disko runs perfectly well without importing the module — handy from a rescue ISO:

Or against a flake, resolving .diskoConfigurations.<attr> first and falling back to the disko module of .nixosConfigurations.<attr>:

format is idempotent — it skips anything blkid already recognises. That makes format,mount safe to re-run when you have added a disk, and mount alone the right way to bring an existing installation back up for repair.

Importing disko.nixosModules.disko and setting disko.devices does two things at once: it generates the scripts, and it configures NixOS from the same tree.

Build outputs made available on the system:

The --no-filesystems flag is the important part: disko owns fileSystems, and letting nixos-generate-config also write them produces conflicting definitions. Consider nixos-facter instead of nixos-generate-config for hardware detection.

For remote or unattended installs, nixos-anywhere drives disko over SSH for you — it kexecs into an installer, runs the disko script, and installs, all from one command.

Per partition:

A partition with no content is simply created and left alone, which is exactly what an EF02 BIOS-boot partition wants.

Set DISKO_SKIP_SWAP=1 in the environment to make the mount stage skip swapon — useful in low-memory or nested-VM situations.

passwordFile is a formatting-time secret. It must exist on the installer, not on the installed system — which is why nixos-anywhere has --disk-encryption-keys and the image builder has --pre-format-files.

lvm_pv has exactly one meaningful option, vg, naming the volume group it belongs to. The group itself:

Thin pools are created before regular LVs (priority 501 vs 1000), and anything sized with 100% is pushed to the back.

mdraid carries only name, pointing at a top-level mdadm array:

zfs content carries only pool. The pool:

Datasets are either zfs_fs (options, mountOptions, mountpoint) or zfs_volume (adds size, extraArgs and a content chain, so you can put ext4 or swap on a zvol). Note the difference between the ZFS property options.mountpoint and disko's own mountpoint: the former is what ZFS records, the latter is what disko mounts during install. options.mountpoint = "legacy" plus a disko mountpoint gives you fileSystems-managed ZFS.

Multi-device bcachefs is split like LVM: each partition gets type = "bcachefs" with filesystem (which named filesystem it joins), an optional label for device groups (group_a.vdb2), and extraFormatArgs. The filesystem itself lives under bcachefs_filesystems.<name> with subvolumes, mountpoint, passwordFile, uuid and extraFormatArgs.

For filesystems with no backing device. The attribute name is the mountpoint:

Every node — entry point or content — accepts six escape hatches, each a block of shell:

preCreateHook, postCreateHook, preMountHook, postMountHook, preUnmountHook, postUnmountHook

The classic use is taking the blank snapshot an impermanence setup rolls back to:

Upstream ships two sets: disko-templates holds curated, best-practice layouts (single-disk-ext4, single-ext4-luks-and-double-zfs-mirror, zfs-impermanence), while the example directory holds ~40 configs that double as the regression test suite — broader coverage, but with test-only quirks (10M partitions, /tmp/secret.key) you must edit out.

The layouts below are trimmed for real use. In all of them, replace device with a stable /dev/disk/by-id/… path.

The safe default. Boots on any UEFI machine.

umask=0077 on the ESP keeps the vfat mount from being world-readable, which otherwise trips systemd's /boot permission warnings.

Same disk boots on old and new firmware. Requires GRUB with efiSupport; disko sets boot.loader.grub.device for you.

A layout that leaves room for snapshots and keeps /nix out of them.

Subvolume names and mountpoints are independent. A nested subvolume whose parent is already mounted needs no mountpoint of its own.

Full-disk encryption with flexible volumes underneath. Everything but /boot is encrypted.

Fixed-size volumes must come before the 100%FREE one — disko already handles this via priority, but it's worth knowing why the ordering is not the attribute order.

Root is wiped on every boot; only /nix and /persist survive.

The rollback itself is a boot.initrd.postDeviceCommands (or a systemd initrd service) that restores root-blank over root before the root filesystem is mounted. disko's job stops at making the pristine snapshot exist.

ZFS needs networking.hostId set to a unique 8-hex-digit value, and boot.supportedFilesystems = [ "zfs" ]. Encrypting a parent dataset with mountpoint = "none" means one passphrase unlocks every child.

For a more complex pool, mode takes a topology instead of a string:

Members refer to the disk names in disko.devices.disk, not device paths.

The array is a device, so it gets its own partition table.

Because a disko config is ordinary Nix, generating the per-disk attrset with map/listToAttrs scales to any number of members. The example/with-lib.nix upstream shows the same trick.

Swap randomEncryption = true gives you an encrypted scratch swap at the cost of hibernation; the two options are mutually exclusive in practice.

nixos-install plus partitioning in one step, and it can run from your workstation rather than the target machine — which makes it the neat way to build a bootable USB stick carrying a full NixOS configuration.

--disk <name> <device> overrides the device written in the config, so the same flake can target whatever is plugged in. Options: --mode format|mount (mount only, to repair an existing install without touching data), --write-efi-boot-entries (off by default, since the target may be portable), --extra-files SRC DEST, --system-config JSON, --mount-point PATH, --dry-run.

It also works fully offline if the installer's closure includes diskoScript, its drvPath and the flake inputs — see the upstream disko-install.md.

Build a .raw from a NixOS configuration, without ever touching real hardware:

The script boots a VM, runs disko inside it, installs, and drops the images in the working directory named after disko.devices.disk.<name> (override with imageName, size with imageSize). Two flags handle secrets:

system.build.diskoImages does the same inside the nix sandbox: reproducible and cacheable, but slower and with no secure way to inject secrets.

Cross-architecture images work through binfmt:

There is no auto-resize yet, so imageSize has to be generous enough for the whole closure.

Boot your real disk layout in QEMU before committing it to hardware:

Unlike the stock config.system.build.vm, this one actually runs the disko scripts, so LUKS prompts, ZFS pools and subvolume mounts all behave as they will on the real machine. Configure the variant through virtualisation.vmVariantWithDisko; disk sizes come from imageSize, memory from disko.memSize.

system.build.installTest is a NixOS VM test that installs the configuration onto virtual disks and boots it. disko.tests.bootCommands lets you type an encryption passphrase, disko.tests.extraChecks asserts on the booted system:

nixos-anywhere exposes the same idea as --vm-test, which is the cheapest way to find out that your layout is wrong before you wipe a remote server.

Because the three stages are separate scripts, a few non-obvious workflows fall out: