Declaratively Upgrading NixOS with nixos-rebuild switch: A Practical Task Guide

Desired Outcome

Apply a new /etc/nixos/configuration.nix or a flake‑based configuration, build the updated system, and make the new generation the active boot entry without reinstalling or manually copying files.

Prerequisites

• Working NixOS installation with root access.
• The nixos-rebuild command (bundled with nixos-utils).
• Optional: Nix 2.4+ for flake support. If using a flake, ensure the nix binary is in the PATH.
• At least 2 GB free space in /nix/store for the build (large kernel or glibc upgrades can consume more).
• Back‑up of /etc/nixos/configuration.nix or the flake repository if you want a quick revert before the build.

Focused Procedure

1. Prepare the configuration

   Either edit /etc/nixos/configuration.nix or create a flake. For a flake, place flake.nix in the repository root and add a hosts directory with a host‑specific default.nix.

   # flake.nix
   { inputs, outputs, ... }:
   { outputs = { nixosConfigurations, ... }:
       let
         system = "x86_64-linux";
         host = "my-host";
       in
       { ${host} = nixosConfigurations.${host}.override {
           modules = [ ./hosts/${host}/default.nix ];
         };
     };
   }
   

2. Verify the configuration syntax

   Run nix flake check . (flake) or nixos-rebuild test (classic) to ensure no errors. No state change occurs.

   sudo nix flake check .
   # or
   sudo nixos-rebuild test
   

3. Build and activate the new generation

   Use --upgrade to fetch the latest packages and switch to activate the new system.

   • Classic configuration:

     sudo nixos-rebuild switch --upgrade
     

   • Flake‑based configuration:

     sudo nixos-rebuild switch --upgrade --flake .#my-host
     

   During the build you’ll see stages: building the Nix store, generating the new system profile, and installing the boot loader. If the kernel or initrd changes, a reboot will be required for the new generation to take effect.

4. Automatic reboot (if needed)

   When the kernel is upgraded, nixos-rebuild prints a message like:

   run `systemctl reboot` to use the new kernel.
   

   Execute that command or simply press Ctrl‑Alt‑Del.

Expected Checks

• List generations

  Verify the new generation is current:

  sudo nixos-rebuild list-generations
  # The last line should have a '*' indicating the active generation.
  

• Kernel version consistency

  Compare the running kernel with the one in the new system profile:

  uname -r
  /run/current-system/sw/bin/uname -r
  

  Both should match.
• Service status

  Test a service that was enabled or modified. For example, if services.sshd.enable = true;:

  systemctl is-active sshd.service
  # Should output "active".
  

• Boot loader entry

  Reboot and confirm GRUB lists the new generation as the default entry. The entry name contains the generation number and the date.

Recovery Options

• Boot from a previous generation

  During boot, select a previous entry in the GRUB menu. Each entry corresponds to a NixOS generation.

• Rollback from a running system

  If you are already booted into the new generation but want to revert:

  sudo nixos-rebuild boot --rollback
  # This sets the previous generation as the next boot target.
  # Reboot to activate it.
  

• Delete an unwanted generation

  After verifying the new system works, free space by removing old generations:

  sudo nixos-rebuild remove 123
  # Replace 123 with the generation number.
  

Limitations & Practical Tips

• Large upgrades (e.g., kernel, glibc) can take minutes and require several gigabytes of temporary space. Check df -h /nix/store before starting.
• Using --flake requires Nix 2.4+. Older systems must either upgrade Nix or use the classic configuration.nix workflow.
• Always keep a recent backup of /etc/nixos/configuration.nix or the flake repository; a corrupted configuration can prevent nixos-rebuild from succeeding.
• After a major release upgrade, review the release notes for any configuration changes that need to be migrated.

Concrete Example: Upgrading to NixOS 24.05 with a Flake

1. Clone the flake repository:

   git clone https://github.com/example/nixos-hosts.git my-hosts
   cd my-hosts
   

2. Confirm the flake is valid:

   sudo nix flake check .
   

3. Upgrade and switch:

   sudo nixos-rebuild switch --upgrade --flake .#my-host
   

4. Reboot if prompted, then verify:

   sudo nixos-rebuild list-generations
   uname -r
   systemctl is-active sshd.service
   

Diagram

Label
Configuration File
nixos-rebuild
System Generation
Boot Loader