Nixos-rebuild

nixos-rebuild is the NixOS command used to apply changes made to the system configuration. It can also be used for a variety of other tasks related to managing the state of a NixOS system.

Basic functionality

NixOS follows a "declarative configuration" approach, which means that the proper way to modify your system is to make changes to your system configuration (typically /etc/nixos/configuration.nix), and then rebuild your system with nixos-rebuild:

$ # Edit your configuration
$ sudo nano /etc/nixos/configuration.nix
$ # Rebuild your system
$ sudo nixos-rebuild switch

The switch subcommand will rebuild your system, activate the new generation immediately and make it the default boot option. There are also a couple of other sub-commands available:

• boot: Build the configuration and make it the default boot option, but don't activate it until the next reboot
• test: Build the configuration and activate it, but don't add it to the bootloader menu
• build: Build the configuration and place a symlink called result pointing to the derivation in the Nix store in the current directory
• dry-activate: Build the configuration, but do not activate it. Instead, show the changes that would be performed by activating the new generation.
• build-vm: Build a QEMU VM that runs the new configuration. It leaves a symlink called result in the current directory that contains the built VM. To run it, use result/bin/run-<hostname>-vm

Useful options include:

• --rollback: Don't build the new configuration, but use the previous generation instead. Useful for quickly reverting erroneous changes, i. e. nixos-rebuild --rollback switch
• --upgrade: Update the nixos channel of the root user before building the configuration.

nixos-rebuild can also be used to build and deploy system configurations on remote hosts via SSH. To use a remote host to build your system and deploy it on the current host, use:

# nixos-rebuild --build-host user@example.com switch

To build the system locally and deploy it on a remote host, use:

$ nixos-rebuild --target-host user@example.com switch

Note that this will often require using a different configuration than the one in /etc/nixos. See the Specifying a different configuration location section for details. --build-host and --target-host can be used simultaneously, even with different hosts.

If you are rebuilding a remote host as a non-root user, use the --use-remote-sudo option to elevate on the remote machine during the rebuilding process:

$ nixos-rebuild --target-host user@example.com --use-remote-sudo switch

Note: When rebuilding a remote host, you may see similar errors to the following:

error: cannot add path '/nix/store/...' because it lacks a signature by a trusted key

If this occurs, add your non-root user or group to the trusted-users list in /etc/nix/nix.conf, which is the nix.settings.trusted-users option in NixOS.

For a full list of sub-commands and options, see the nixos-rebuild man page.

Specifying a different configuration location

without Flakes

By default, nixos-rebuild builds the configuration in the file specified by the nixos-config field in the NIX_PATH environment variable, which is set to /etc/nixos/configuration.nix by default. This can be overwritten with:

# nixos-rebuild switch -I nixos-config=path/to/configuration.nix

To permanently change the location of the configuration, modify the NIX_PATH variable of your system with the nix.nixPath config option:

{
  nix.nixPath = [ "nixos-config=/path/to/configuration.nix" ];
}

with Flakes

nixos-rebuild will look for the file /etc/nixos/flake.nix by default and build the nixosConfigurations item matching the current host name of the system. To specify a different flake directory, use:

# nixos-rebuild switch --flake path/to/flake/directory

To specify a different host name, use:

# nixos-rebuild switch --flake /etc/nixos#hostname

Internals

nixos-rebuild is a Bash script that performs a relatively simple sequence of tasks. In the case of nixos-rebuild switch, these are:

• Build the config.system.build.toplevel derivation of the current configuration. This can be manually done by:

$ # without Flakes
$ nix-build <nixpkgs/nixos> -A config.system.build.toplevel -I nixos-config=path/to/configuration.nix
$ # with Flakes
$ nix build /etc/nixos#nixosConfigurations.hostname.config.system.build.toplevel

• Add the resulting derivation to the system profile in /nix/var/nix/profiles, i. e. create a new generation in the system profile.
• Add the new generation to the bootloader menu as the new default and activate it. If you've manually built the system derivation, this can also be done with result/bin/switch-to-configuration switch.