nixos-rebuild

Build and switch to the new configuration, making it the boot default

$ sudo nixos-rebuild switch

$ sudo nixos-rebuild switch [[-p|--profile-name]] [name]

$ sudo nixos-rebuild switch --upgrade

$ sudo nixos-rebuild switch --rollback

$ sudo nixos-rebuild boot

$ sudo nixos-rebuild test

$ sudo nixos-rebuild build-vm

$ nixos-rebuild list-generations

nixos-rebuild [subcommand] [options...]
Examples:
nixos-rebuild switch
nixos-rebuild boot --flake .#myConfig
nixos-rebuild rollback

switch
    Builds and activates the new configuration immediately. This is the most common subcommand.

boot
    Builds the configuration and sets it as the default boot entry. Requires a reboot to take effect.

test
    Builds the configuration and temporarily loads it into a testing environment without global activation.

dry-run
    Shows the planned changes and derivations that would be built without actually performing the build or activation.

build
    Only builds the specified configuration into the Nix store without activating it.

rollback
    Reverts the system to the previously active configuration generation.

--flake
    Specifies a Nix flake to build the system configuration from. E.g., ., github:NixOS/nixpkgs#nixos-23.11.

-I
    Adds to the Nix search path for finding imported Nix expressions (legacy method).

--upgrade
    Upgrades Nixpkgs before building the configuration. Often used with non-flake setups.

--show-trace
    Displays detailed stack traces during evaluation errors, useful for debugging.

--cores
    Sets the number of CPU cores to use for parallel builds.

--max-jobs
    Sets the maximum number of parallel build jobs.

nixos-rebuild is the central command for managing NixOS system configurations. It takes a declarative Nix expression (typically configuration.nix or a Nix flake) describing the desired system state, builds it using the Nix package manager, and then atomically switches the running system to this new configuration. This process ensures system stability and reproducibility by guaranteeing that all dependencies are correctly built and linked. It supports rolling back to previous system generations, providing a robust mechanism for recovery in case of issues. The command leverages Nix's immutable store and cryptographic hashing to achieve highly reliable and atomic updates, making system management straightforward and safe.

Requires root privileges to perform system-wide changes.
Initial builds or significant configuration changes can consume considerable time and disk space.
Network connectivity is often required to fetch necessary packages and sources.
While rollbacks are atomic for the system configuration, they do not revert changes to user data or persistent state outside the Nix store.

nixos-rebuild exemplifies NixOS's declarative approach, where the desired system state is described in configuration files, and the command ensures the system matches that declaration, rather than imperatively executing steps.

Every successful nixos-rebuild operation creates a new "generation" of the system. This allows for atomic switches between generations and instant rollbacks to any prior working state, providing unparalleled system stability and recovery capabilities.

Modern NixOS configurations often leverage Nix flakes. nixos-rebuild fully supports flakes via the --flake option, enabling reproducible, self-contained, and easily shareable system configurations defined by a flake.nix file.

nixos-rebuild has been a fundamental component of the NixOS project since its inception, embodying the declarative and atomic update philosophy of the operating system. Its evolution has closely mirrored that of the Nix package manager, adapting to new features like the introduction of flakes, which significantly streamlined configuration management and reproducibility. It remains the primary user-facing tool for managing system state on NixOS, solidifying its role as a cornerstone of the distribution.

nix(1), nix-store(1), nix-shell(1), nix-collect-garbage(1), nixos-enter(1)