Skip to content

Disk and persistence

Three separate concerns: declare disks (partitions / fileSystems / disko), wipe root (impermanence / erase-your-darlings), and bootloader (boot.loader.*—not owned by disko). Fresh layout ≠ day-2 FS tuning. Bootstrap chooser: Install and bootstrap.

Decision table

Situation Prefer Leaf Avoid if…
Desktop at the machine; stock erase-disk layout Guided ISO (Calamares) Graphical installer · Install and bootstrap Custom GPT/LUKS/ZFS, dual-boot, or flake-first disko
Console / minimal ISO; learn fdisk → /mnt → install Manual partition + nixos-generate-config Manual install You want the layout in Nix and reusable across hosts
Declarative disks in config; apply from installer disko (destroy,format,mount then install) disko Sharing the disk with another OS; wrong /dev/disk/by-id/…
Local / boot media: partition + nixos-install in one step disko-install disko Remote-only host (use nixos-anywhere); dual-boot (destructive wipe)
Need a starter GPT / LUKS / ZFS-impermanence layout disko-templates / recipe patterns Disko recipes Expecting bootloader or impermanence bind-mounts from the template alone (zfs-impermanence ≠ the module)
Pool/subvol knobs, scrub, native encryption vs LUKS ZFS / Btrfs modules after layout exists ZFS and Btrfs Still choosing partitions—finish disko / manual layout first
Ephemeral root; declare survivors on /persist (or /persistent) impermanence module + durable /nix /boot Impermanence Secrets / decrypt keys left only on wiped root; layout template alone without the module
Share disk with Windows / another Linux Careful manual or shared-ESP dual-boot path Dual boot and VMs · Partitioning and bootloaders disko destructive modes aimed at whole-disk wipe
Fresh NixOS over SSH (kexec → disko → flake) nixos-anywhere nixos-anywhere Day-2 updates; keeping an existing foreign OS on the target disk

disko owns mounts → generate hardware with nixos-generate-config --no-filesystems: hardware-configuration. Persist decrypt identities: Secrets strategies.

Failure callouts

Symptom / mistake Fix
Wrong /dev/disk/by-id/… (or /dev/sdX) + destroy/format Verify ls -l /dev/disk/by-id before any destructive disko mode; wrong device = wiped data (disko · recipes)
Dual-boot + disko destructive layout Dual-boot is not a disko goal—use manual / dual-boot paths that leave the other OS intact
Forgot neededForBoot on persist / ephemeral volumes Mark persistent and ephemeral storage volumes neededForBoot so early bind/link (e.g. /etc/machine-id) works—Impermanence
zfs-impermanence (or other template) but state still vanishes / no bind-mounts Template only creates pool/datasets; wire impermanence (environment.persistence."…") or equivalent—Disko recipes
Secrets or age/SSH decrypt keys only on ephemeral root Keep identities + ciphertext on the persist volume; decrypt into /run—Secrets strategies
Disks mounted but no bootloader enabled disko ≠ bootloader—set boot.loader.systemd-boot.enable or boot.loader.grub.enable (Partitioning and bootloaders)

See also

References