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