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 [command] [options]

switch
    Activate the new configuration immediately.

boot
    Set the new configuration as the default for the next boot.

test
    Build the configuration and test it using QEMU. Requires hardware virtualization support.

dry-run
    Show what would be built without actually building anything.

-I nixpkgs=
    Specify the Nix Packages collection to use. Useful for testing unreleased changes.

--upgrade
    Attempt to upgrade existing packages rather than rebuilding from scratch.

--rollback
    Switch to the previous system configuration.

--flake #
    Build and switch to a configuration defined by a Nix flake.

The nixos-rebuild command is the primary tool for applying configuration changes in NixOS. It reads the system's Nix configuration files (typically /etc/nixos/configuration.nix and imported modules) and generates a new system configuration. This involves building all necessary packages, creating the system closure (a set of dependencies needed to run the system), and updating the bootloader to boot into the new configuration.

The command offers various targets, each serving a specific purpose. For example, switch activates the new configuration immediately, while boot sets the new configuration as the default for the next boot. Other targets allow for testing or building Docker images based on the NixOS configuration.

Nixos-rebuild ensures atomic upgrades by maintaining multiple system generations. If a new configuration fails, you can easily rollback to a previous working one. It's a core component of NixOS's declarative and reproducible system management approach.

Requires root privileges to execute. Changes to the system configuration should be carefully reviewed before applying, as incorrect configurations can lead to system instability.

NixOS maintains multiple system generations, allowing users to easily revert to a previous, working configuration if a new one causes problems. These generations are managed automatically by nixos-rebuild. After a successful switch/boot it will cleanup old generations based on `system.gc.max-age` and `system.gc.automatic` options

The system configuration is defined in Nix expressions, typically located in /etc/nixos/configuration.nix. These expressions describe the desired state of the system, including installed packages, system services, and hardware settings. NixOS then uses these expressions to build the system closure.

Configuration files can `import` other configuration files and/or Nix expressions. Best practice is to organize the modules in `/etc/nixos/hardware.nix` for example.

User accounts, groups and their settings are defined declaratively in the NixOS configuration files. This ensures consistent user management across system generations. See `users.users.*` NixOS options.

nixos-rebuild emerged alongside the NixOS project itself, designed to facilitate reproducible and declarative system management. Its development has been tightly linked to the evolution of Nix and the Nix Packages collection (Nixpkgs). Initially focused on simple system rebuilding and switching, it has grown to encompass a wider range of targets (boot, test, dry-run) and integration with modern Nix features like flakes.

nix(1), nix-env(1), bootctl(1)