nixos-rebuild
Apply NixOS configuration changes
TLDR
Build and switch to the new configuration, making it the boot default
Build and switch to the new configuration, making it the boot default and naming the boot entry
Build and switch to the new configuration, making it the boot default and installing updates
Rollback changes to the configuration, switching to the previous generation
Build the new configuration and make it the boot default without switching to it
Build and activate the new configuration, but don't make a boot entry (for testing purposes)
Build the configuration and open it in a virtual machine
List available generations similar to the boot loader menu
SYNOPSIS
nixos-rebuild [command] [options]
PARAMETERS
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.
DESCRIPTION
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.
CAVEATS
Requires root privileges to execute. Changes to the system configuration should be carefully reviewed before applying, as incorrect configurations can lead to system instability.
SYSTEM GENERATIONS
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
CONFIGURATION FILES
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 MANAGEMENT
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.
HISTORY
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.