Atomic Upgrades and Safe Rollbacks in NixOS: How Generations Protect Your System

The problem: a broken upgrade leaves you stranded

You run nixos-rebuild switch to apply a new set of packages or a kernel change. The command appears to succeed, but after reboot the system fails to start a critical service, or the new kernel panics. Without a safety net you would need to reinstall or manually chroot into a rescue environment to recover.

Thesis: NixOS treats each system configuration as an immutable generation, making upgrades atomic and rollbacks straightforward—as long as the generations are preserved.

How generations are created

Every time you invoke nixos-rebuild switch (or nixos-rebuild test followed by a manual switch), Nix evaluates your configuration.nix and builds a complete system derivation. This derivation includes the kernel, all packages, systemd units, and the GRUB configuration. The result is stored in the Nix store under a path like /nix/store/...-nixos-system-.... A symlink /run/current-system is then updated to point to the new path, and the boot loader entry is regenerated. Because the store is content‑addressed, the previous generation remains untouched and immutable.

Performing an atomic upgrade

1. Edit /etc/nixos/configuration.nix (or a module) to add or change packages.
2. Run the rebuild as root:

   sudo nixos-rebuild switch

3. The command downloads any missing sources, builds the new generation, and atomically swaps /run/current-system. If any step fails, the symlink is left pointing at the old generation, so the running system is unchanged.

Rolling back to a known good generation

If the new generation proves problematic, you have two immediate options:

• Reboot and select the previous entry from the GRUB menu (usually labeled "NixOS - ").
• From a running system, execute:

  sudo nixos-reboot --rollback

  This tells the boot loader to boot the previous generation on the next start.

Both actions rely on the existence of at least one prior generation in the Nix store.

Worked example: upgrading the kernel and verifying rollback

Assume you want to test the latest Linux kernel from the unstable channel.

1. Add the kernel to your configuration:

     boot.kernelPackages = pkgs.linuxKernel_6_10;

2. Run the upgrade:

   sudo nixos-rebuild switch

   You will see output like "building /nix/store/...-nixos-system-...-drv" and finally "activating the configuration...".
3. Reboot:

   sudo reboot

   If the system fails to boot, hold Shift (or Esc on UEFI) to show GRUB, choose the entry that ends with the previous generation number, and boot into it.
4. Once back in a working system, confirm the rollback by checking the active generation:

   # Show the current generation
       sudo nix-env -p /nix/var/nix/profiles/system --list-generations
       # Expected output includes the generation you just rolled back to, marked as current.
       

5. Optionally, compare the configuration files:

   diff /run/current-system/configuration.nix /etc/nixos/configuration.nix
       # Should show no differences if the rollback succeeded.
       

Trade‑off: generation retention versus garbage collection

NixOS keeps only the last two generations by default (controlled by nixpkgs.nixos.system.autoUpgrade.keepGenerations). If you enable aggressive garbage collection—for example, by setting nix.gc.options = [ "--delete-older-than" "30d" ]—older generations may be removed before you have a chance to roll back. This can turn a recoverable mistake into a situation requiring a reinstall or manual chroot recovery.

To verify that your rollback safety is intact, periodically run:

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

Ensure the list includes at least the current generation and one previous generation. If you see only a single entry, adjust your GC settings or manually retain a generation with:
sudo nix-env -p /nix/var/nix/profiles/system --delete-generations +

Replace + with the generation number you wish to keep.
Actionable closing
Atomic upgrades in NixOS give you confidence to experiment, but the safety net depends on preserving generations. Make it a habit to:

  
Run nixos-rebuild switch as root and watch for any build failures.
  
After a reboot, verify the new generation booted successfully.
  
If something goes wrong, use the GRUB menu or nixos-reboot --rollback to return to the prior generation.
  
Periodically check generation counts to ensure garbage collection hasn’t erased your rollback options.

By treating each system state as an immutable snapshot and honoring the generation lifecycle, you can enjoy the cutting‑edge packages of NixOS without fearing an unrecoverable break.