Atomic Upgrades and Rollbacks in NixOS: Using Generations for Safe System Changes

Problem: Making a system change without risking an unbootable machine

When you edit /etc/nixos/configuration.nix to add a service, change a kernel parameter, or update a package set, a mistake can leave the system unable to boot. On traditional Linux distributions you might need to boot from a live USB, chroot, and manually fix the mistake. NixOS avoids this by treating every configuration change as an immutable snapshot called a generation. The useful takeaway is that you can test a new configuration, and if it fails, you can return to the exact previous state with a single boot‑menu choice or command.

How generations work

Each time you run sudo nixos-rebuild switch, NixOS evaluates your configuration.nix, builds the exact set of packages and services described, and stores the result in the Nix store under a path like /nix/var/nix/profiles/system-link. A new entry is added to the boot loader’s menu (GRUB by default) that points to this snapshot. The entry is numbered sequentially – the first boot after installation is generation 1, the next change creates generation 2, and so on. Because the store is purely functional, the files for each generation are never mutated; they are hard‑linked to the same underlying store objects, which keeps disk usage low.

Worked example: adding a simple service and verifying the new generation

1. Open your configuration file:

   sudo $EDITOR /etc/nixos/configuration.nix

2. Add a trivial service, for instance enabling the echo daemon:

     services.echo.enable = true;

3. Save and rebuild:

   sudo nixos-rebuild switch

   This command activates the new generation atomically; the shell prompt returns only after the new system is running.

4. List generations to see the new entry:

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

   You should see output similar to:

     1   2026-09-01 12:00:00   (current)
     2   2026-09-15 08:30:00
     3   2026-10-09 16:45:00   (active)

   The highest number is the active generation. You can confirm the service is running with:

   systemctl status echo.service

Rolling back to a previous generation

If the new configuration causes a boot failure, you have two immediate options:

• From the GRUB menu at boot time, choose the entry labeled with the previous generation number (e.g., “NixOS Generation 2”). The system will load the exact snapshot that was active before the change.

• If the system is still bootable, you can roll back without rebooting:

  sudo nixos-rebuild switch --rollback

  This command activates the generation directly before the current one, equivalent to selecting the prior GRUB entry.

After a rollback, run the generation list command again to verify that the active generation number has decreased by one.

Trade‑offs and limitations

While generations give you atomic upgrades and easy rollbacks, they do not revert user‑modified data. Files in /home, databases, or any state stored outside the Nix store remain unchanged when you roll back. If you need to revert data as well, you must snapshot those locations separately (e.g., with ZFS snapshots or LVM).

Frequent rebuilds increase the number of generations, which can consume disk space in the Nix store. NixOS automatically garbage‑collects generations older than 30 days via nix-collect-garbage -d. You can adjust retention by setting:

  nix.gc.automatic = true;
  nix.gc.options = [ "--delete-older-than 30d" ];

in configuration.nix. Monitoring du -sh /nix helps you gauge whether the store is growing unexpectedly.

Actionable closing

To make generations part of your workflow:

1. After any nixos-rebuild switch, run the generation list command to confirm a new entry appears.

2. If you suspect a bad change, first try sudo nixos-rebuild switch --rollback; if the system won’t boot, use the GRUB menu.

3. Periodically check /nix size and tweak garbage‑collection settings if you notice steady growth.

By treating each configuration change as an immutable snapshot, NixOS lets you experiment with system updates confidently, knowing you can always return to a known‑good state.