nixos-rebuild8NixOSnixos-rebuildreconfigure a NixOS machinenixos-rebuildbuilder-specflake-uriinput-nameflake-urinamenamehosthostNIX_PATHnumberDescription
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:
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.
Note that if you are using specializations, running just
nixos-rebuild switch will switch you back to the
unspecialized, base system - in that case, you might want to use this
instead:
$ nixos-rebuild switch --specialisation your-specialisation-name
This command will build all specialisations and make them bootable just
like regular nixos-rebuild switch does - the only
thing different is that it will switch to given specialisation instead
of the base system; it can be also used to switch from the base system
into a specialised one, or to switch between specialisations.
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.
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).
Note that if you are using specialisations, running just
nixos-rebuild test will activate the unspecialised,
base system - in that case, you might want to use this instead:
$ nixos-rebuild test --specialisation your-specialisation-name
This command can be also used to switch from the base system into a
specialised one, or to switch between specialisations.
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.
Show what store paths would be built or downloaded by any of the
operations above, but otherwise do nothing.
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.
Opens configuration.nix in the default editor.
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.
Like , 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:
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 updates all of the root
user's channels.
Causes the boot loader to be (re)installed on the device specified by the
relevant configuration options.
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.
Equivalent to . This option is
useful if you call nixos-rebuild frequently
(e.g. if you’re hacking on a NixOS module).
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.)
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.settings.trusted-users 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.
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'”.
Activates given specialisation; when not specified, switching and testing
will activate the base, unspecialised system.
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
is not set, the build will be copied back
to the local machine when done.
Note that, if 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.
Specifies the NixOS target host. By setting this to something other than
an empty string, 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 ,
and you need root access.
If is not explicitly specified or empty,
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.
Note that nixos-rebuild honors the
nixpkgs.crossSystem setting of the given configuration
but disregards the true architecture of the target host. Hence the
nixpkgs.crossSystem setting has to match the target
platform or else activation will fail.
When set, nixos-rebuild will add
to each invocation of nix-copy-closure. This will only affect the
behavior of nixos-rebuild if or
is also set. This is useful when
the target-host connection to cache.nixos.org is faster than the
connection between hosts.
When set, nixos-rebuild prefixes remote commands that run on
the and
systems with sudo. Setting this option allows
deploying as a non-root user.
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.
Do not imply if
/etc/nixos/flake.nix exists. With this
option, it is possible to build non-flake NixOS configurations
even if the current NixOS systems uses flakes.
In addition, nixos-rebuild accepts various Nix-related
flags, including / , ,
, ,
, , and /
. See the Nix manual for details.
EnvironmentNIXOS_CONFIG
Path to the main NixOS configuration module. Defaults to
/etc/nixos/configuration.nix.
NIX_PATH
A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (e.g <nixpkgs>). Example
nixpkgs=./my-nixpkgs
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 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.