nixos-rebuild - Man Page

reconfigure a NixOS machine

Examples (TL;DR)

tldr.sh

Synopsis

nixos-rebuild {switch | boot | test | build | dry-build | dry-activate | edit | build-vm | build-vm-with-bootloader}
[{ --upgrade | --upgrade-all }] [--install-bootloader] [--no-build-nix] [--fast] [--rollback] [--builders builder-spec]
[--flake flake-uri] [--override-input input-name flake-uri]
[{ --profile-name | -p } name]
[--build-host host] [--target-host host] [--use-remote-sudo]
[--show-trace] [-I path] [{--verbose | -v}] [{--impure}] [{--max-jobs | -j} number] [{--keep-failed | -K}] [{--keep-going | -k}]

Description

This command updates the system so that it corresponds to the configuration specified in /etc/nixos/configuration.nix or /etc/nixos/flake.nix. Thus, every time you modify the configuration or any other NixOS module, you must run nixos-rebuild to make the changes take effect. It builds the new system in /nix/store, runs its activation script, and stop and (re)starts any system services if needed. Please note that user services need to be started manually as they aren't detected by the activation script at the moment.

This command has one required argument, which specifies the desired operation. It must be one of the following:

switch

Build and activate the new configuration, and make it the boot default. That is, the configuration is added to the GRUB boot menu as the default menu entry, so that subsequent reboots will boot the system into the new configuration. Previous configurations activated with nixos-rebuild switch or nixos-rebuild boot remain available in the GRUB menu.

boot

Build the new configuration and make it the boot default (as with nixos-rebuild switch), but do not activate it. That is, the system continues to run the previous configuration until the next reboot.

test

Build and activate the new configuration, but do not add it to the GRUB boot menu. Thus, if you reboot the system (or if it crashes), you will automatically revert to the default configuration (i.e. the configuration resulting from the last call to nixos-rebuild switch or nixos-rebuild boot).

build

Build the new configuration, but neither activate it nor add it to the GRUB boot menu. It leaves a symlink named result in the current directory, which points to the output of the top-level “system” derivation. This is essentially the same as doing

$ nix-build /path/to/nixpkgs/nixos -A system

Note that you do not need to be root to run nixos-rebuild build.

dry-build

Show what store paths would be built or downloaded by any of the operations above, but otherwise do nothing.

dry-activate

Build the new configuration, but instead of activating it, show what changes would be performed by the activation (i.e. by nixos-rebuild test). For instance, this command will print which systemd units would be restarted. The list of changes is not guaranteed to be complete.

edit

Opens configuration.nix in the default editor.

build-vm

Build a script that starts a NixOS virtual machine with the desired configuration. It leaves a symlink result in the current directory that points (under result/bin/run-hostname-vm) at the script that starts the VM. Thus, to test a NixOS configuration in a virtual machine, you should do the following:

$ nixos-rebuild build-vm
$ ./result/bin/run-*-vm

The VM is implemented using the qemu package. For best performance, you should load the kvm-intel or kvm-amd kernel modules to get hardware virtualisation.

The VM mounts the Nix store of the host through the 9P file system. The host Nix store is read-only, so Nix commands that modify the Nix store will not work in the VM. This includes commands such as nixos-rebuild; to change the VM’s configuration, you must halt the VM and re-run the commands above.

The VM has its own ext3 root file system, which is automatically created when the VM is first started, and is persistent across reboots of the VM. It is stored in ./hostname.qcow2.

build-vm-with-bootloader

Like build-vm, but boots using the regular boot loader of your configuration (e.g., GRUB 1 or 2), rather than booting directly into the kernel and initial ramdisk of the system. This allows you to test whether the boot loader works correctly. However, it does not guarantee that your NixOS configuration will boot successfully on the host hardware (i.e., after running nixos-rebuild switch), because the hardware and boot loader configuration in the VM are different. The boot loader is installed on an automatically generated virtual disk containing a /boot partition.

Options

This command accepts the following options:

--upgrade,  --upgrade-all

Update the root user's channel named nixos before rebuilding the system.

In addition to the nixos channel, the root user's channels which have a file named .update-on-nixos-rebuild in their base directory will also be updated.

Passing --upgrade-all updates all of the root user's channels.

--install-bootloader

Causes the boot loader to be (re)installed on the device specified by the relevant configuration options.

--no-build-nix

Normally, nixos-rebuild first builds the nixUnstable attribute in Nixpkgs, and uses the resulting instance of the Nix package manager to build the new system configuration. This is necessary if the NixOS modules use features not provided by the currently installed version of Nix. This option disables building a new Nix.

--fast

Equivalent to --no-build-nix. This option is useful if you call nixos-rebuild frequently (e.g. if you’re hacking on a NixOS module).

--rollback

Instead of building a new configuration as specified by /etc/nixos/configuration.nix, roll back to the previous configuration. (The previous configuration is defined as the one before the “current” generation of the Nix profile /nix/var/nix/profiles/system.)

--builders builder-spec

Allow ad-hoc remote builders for building the new system. This requires the user executing nixos-rebuild (usually root) to be configured as a trusted user in the Nix daemon. This can be achieved by using the nix.trustedUsers NixOS option. Examples values for that option are described in the Remote builds chapter in the Nix manual, (i.e. --builders "ssh://bigbrother x86_64-linux"). By specifying an empty string existing builders specified in /etc/nix/machines can be ignored: --builders "" for example when they are not reachable due to network connectivity.

--profile-name,  -p

Instead of using the Nix profile /nix/var/nix/profiles/system to keep track of the current and previous system configurations, use /nix/var/nix/profiles/system-profiles/name. When you use GRUB 2, for every system profile created with this flag, NixOS will create a submenu named “NixOS - Profile 'name'” in GRUB’s boot menu, containing the current and previous configurations of this profile.

For instance, if you want to test a configuration file named test.nix without affecting the default system profile, you would do:

$ nixos-rebuild switch -p test -I nixos-config=./test.nix

The new configuration will appear in the GRUB 2 submenu “NixOS - Profile 'test'”.

--build-host

Instead of building the new configuration locally, use the specified host to perform the build. The host needs to be accessible with ssh, and must be able to perform Nix builds. If the option --target-host is not set, the build will be copied back to the local machine when done.

Note that, if --no-build-nix is not specified, Nix will be built both locally and remotely. This is because the configuration will always be evaluated locally even though the building might be performed remotely.

You can include a remote user name in the host name (user@host). You can also set ssh options by defining the NIX_SSHOPTS environment variable.

--target-host

Specifies the NixOS target host. By setting this to something other than localhost, the system activation will happen on the remote host instead of the local machine. The remote host needs to be accessible over ssh, and for the commands switch, boot and test you need root access.

If --build-host is not explicitly specified, building will take place locally.

You can include a remote user name in the host name (user@host). You can also set ssh options by defining the NIX_SSHOPTS environment variable.

--use-substitutes

When set, nixos-rebuild will add --use-substitutes to each invocation of nix-copy-closure. This will only affect the behavior of nixos-rebuild if --target-host or --build-host is also set. This is useful when the target-host connection to cache.nixos.org is faster than the connection between hosts.

--use-remote-sudo

When set, nixos-rebuild prefixes remote commands that run on the --build-host and --target-host systems with sudo. Setting this option allows deploying as a non-root user.

--flake flake-uri[#name]

Build the NixOS system from the specified flake. It defaults to the directory containing the target of the symlink /etc/nixos/flake.nix, if it exists. The flake must contain an output named nixosConfigurations.name. If name is omitted, it default to the current host name.

In addition, nixos-rebuild accepts various Nix-related flags, including --max-jobs / -j, --show-trace, --keep-failed, --keep-going, --impure, and --verbose / -v. See the Nix manual for details.

Environment

NIXOS_CONFIG

Path to the main NixOS configuration module. Defaults to /etc/nixos/configuration.nix.

NIX_SSHOPTS

Additional options to be passed to ssh on the command line.

Files

/etc/nixos/flake.nix

If this file exists, then nixos-rebuild will use it as if the --flake option was given. This file may be a symlink to a flake.nix in an actual flake; thus /etc/nixos need not be a flake.

/run/current-system

A symlink to the currently active system configuration in the Nix store.

/nix/var/nix/profiles/system

The Nix profile that contains the current and previous system configurations. Used to generate the GRUB boot menu.

Bugs

This command should be renamed to something more descriptive.

Author

Eelco Dolstra

Author

Info

01/01/1980 NixOS Reference Pages