Managing NixOS Generations for Safe Upgrades and Disk Space

Why Generation Management Matters

When you run nixos-rebuild switch, NixOS builds a new system generation and swaps the symlink at /nix/var/nix/profiles/system to point to the fresh store path. The previous generation stays available as a boot option, giving you an atomic upgrade and an instant rollback path.

Listing and Inspecting Generations

You can see what generations exist with:

nix-env --list-generations -p /nix/var/nix/profiles/system

Each line shows a number, a timestamp and the store path. The current generation is also readable via:

readlink /nix/var/nix/profiles/system

This returns something like /nix/store/abcdef123456‑system‑....

Creating a New Generation

Assuming you have edited /etc/nixos/configuration.nix (or a flake), run as root:

sudo nixos-rebuild switch

This command:

• Builds the new closure in the Nix store.
• Atomically replaces the system symlink.
• Adds a new GRUB menu entry for the fresh generation.

After it finishes, verify the symlink changed:

readlink /nix/var/nix/profiles/system

You should see a different store path than before.

Rolling Back to the Previous Generation

If the new system fails to boot or you want to revert immediately, you can:

sudo nixos-rebuild boot --rollback

This updates the boot entry to use the previous generation without rebuilding. On the next reboot, the GRUB menu will highlight the earlier generation. To test the rollback without rebooting, you can also activate the previous generation temporarily:

sudo nixos-rebuild switch --rollback

Note that this only rewinds the system configuration and packages; files in /var, /home, or any database you manage remain unchanged.

Cleaning Old Generations

Each generation keeps its entire store‑path closure, so disk usage grows linearly with the number of retained generations. To reclaim space, run the garbage collector:

sudo nix-collect-garbage -d

The -d flag deletes generations that are no longer referenced by the system profile. You can first see what would be removed with:

sudo nix-collect-garbage --dry-run -d

After collecting, check the freed space with df -h /nix.

Trade‑offs and Practical Tips

Keeping many generations gives you a long safety net but can fill a small /nix partition quickly. A common practice is to retain the last two or three generations and run garbage collection weekly via a systemd timer or cron job. Remember that rollback does not restore mutable state; back up databases, logs, or user data separately if you need to revert those as well.

Actionable Checklist

1. List current generations: nix-env --list-generations -p /nix/var/nix/profiles/system
2. Apply changes: sudo nixos-rebuild switch
3. Verify symlink update with readlink /nix/var/nix/profiles/system
4. If needed, rollback: sudo nixos-rebuild boot --rollback
5. Periodically clean: sudo nix-collect-garbage -d (dry‑run first)
6. Monitor /nix usage: df -h /nix

Following these steps gives you reproducible upgrades, instant rollback capability, and control over disk consumption.