nixos-rebuild(8)

📦
version 26.11 · 2 versions
, in nixpkgs unstable

✨ NAME ✨

nixos-rebuild — the command that reconfigures a NixOS machine 💅 (straight out of the System Manager's Manual, section 8, iykyk)

🎀 SYNOPSIS 🎀

okay so here's the whole vibe, every flag, no cap:

nixos-rebuild [--verbose] [--quiet] [--max-jobs MAX_JOBS] [--cores
CORES] [--log-format LOG_FORMAT] [--keep-going] [--keep-failed]
[--fallback] [--repair] [--option OPTION OPTION] [--builders BUILDERS]
[--include INCLUDE]
[--print-build-logs] [--show-trace] [--accept-flake-config] [--refresh]
[--impure] [--offline] [--no-net] [--recreate-lock-file]
[--no-update-lock-file] [--no-write-lock-file] [--no-registries]
[--commit-lock-file]
[--update-input UPDATE_INPUT] [--override-input OVERRIDE_INPUT
OVERRIDE_INPUT] [--no-build-output] [--use-substitutes] [--help]
[--debug] [--file FILE] [--attr ATTR] [--flake [FLAKE]] [--no-flake]
[--install-bootloader]
[--profile-name PROFILE_NAME] [--specialisation SPECIALISATION]
[--rollback] [--store-path STORE_PATH] [--upgrade] [--upgrade-all]
[--json] [--elevate {none,sudo,run0}] [--ask-elevate-password]
[--no-reexec]
[--build-host BUILD_HOST] [--target-host TARGET_HOST] [--no-build-nix]
[--image-variant IMAGE_VARIANT]
[{switch,boot,test,build,edit,repl,dry-build,dry-run,dry-activate,build-image,build-vm,build-vm-with-bootloader,list-generations}]

🌸 DESCRIPTION 🌸

okay bestie, here's the whole thing 🫶 This command updates the system so that it corresponds to the configuration specified in /etc/nixos/configuration.nix, /etc/nixos/flake.nix, /etc/nixos/system.nix — or whatever file and attribute you point at with the --file, --attr or --flake options. So basically every single time you touch the config or any other NixOS module, you have to run nixos-rebuild to make those changes actually take effect. That's the whole gig ✨

What it does under the hood: it builds the new system in /nix/store, runs its activation script, then stops and (re)starts any system services if needed. Iconic. But heads up: user services need to be started manually, because the activation script doesn't detect them at the moment 😭

This command has one required argument, and it 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. slay 💅

⚠️ Important vibe check: if you're using specialisations, 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 a regular nixos-rebuild switch does — the only thing different is that it will switch to the given specialisation instead of the base system; it can also be used to switch from the base system into a specialised one, or to switch between specialisations. so versatile, honestly 👑

🥾 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. it's giving "I'll deal with it later" energy 💀

🧪 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. cute little safety net 🌸

⚠️ Same specialisation warning as before: if you're 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 also be used to switch from the base system into a specialised one, or to switch between specialisations. yes bestie, the flexibility 😌

🛠️ 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
💜 ngl the best part: you do not need to be root to run nixos-rebuild build. no sudo, no stress, we love to see it 🫶

🫧 dry-build

Show what store paths would be built or downloaded by any of the operations above — but otherwise do nothing. it's the window-shopping of builds 🙈

👀 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 — so like, it's a preview, not a contract, k? 😭

✏️ edit

Opens configuration.nix in the default editor. simple. elegant. main character energy 💅

🧚 repl

Opens the configuration in nix repl. yes queen, live in the repl 🦋

💿 build-image

Build a disk-image variant, pre-configured for the given platform/provider. Select a variant with the --image-variant option, or run without any options to get a list of available variants:

$ nixos-rebuild build-image --image-variant proxmox

🖥️ 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. So 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 🔥 (fr fr, do this, the difference is real)

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. annoying? yes. the rules? the rules. 💀

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 👑

⚠️ but bestie, caveat time: 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.

📋 list-generations [--json]

List the available generations in a similar manner to the boot loader menu. It shows the generation number, build date and time, NixOS version, kernel version and the configuration revision. There is also a json version of output available ✨ (iykyk, --json is the move for scripting)

  • --upgrade, --upgrade-all — updates the root user's channel named nixos before rebuilding the system. 💅

And like, it's not just that one channel bestie — any of root's channels that have a file named .update-on-nixos-rebuild sitting in their base directory get updated too.

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

  • --install-bootloader — makes the boot loader get (re)installed onto the device that the relevant configuration options point at. ✨
  • --no-reexec — okay so normally nixos-rebuild is extra and first finds + builds itself from the config.system.build.nixos-rebuild attribute of the current user channel or flake, then execs into that copy so you're running with the latest bug-fixes. This flag turns that whole glow-up off and just uses the nixos-rebuild instance you already have. 💀
  • --rollback — instead of building a shiny new configuration as specified by /etc/nixos/configuration.nix, you roll back to the previous configuration. (And "previous" means the one before the current generation of the Nix profile /nix/var/nix/profiles/system.) lowkey the undo button 🫶
  • --store-path path — use a pre-built NixOS system store path at path instead of evaluating and building from the configuration. This skips the evaluation and build phases entirely, no cap. The path must be a valid NixOS system closure — like, it has to contain nixos-version and bin/switch-to-configuration. 👑

This is the move for deploying closures that were built elsewhere, e.g. in CI systems or on remote build machines. iconic.

Can only be used with switch, boot, test, and dry-activate actions. Mutually exclusive with --rollback, --flake, --file, and --attr. And the --build-host option is ignored when --store-path is specified. 🙈

  • --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 — you do that with the nix.settings.trusted-users NixOS option. Example values for that option live in the "Remote builds" chapter of the Nix manual, i.e. --builders "ssh://bigbrother x86_64-linux". 💖

And if you pass an empty string, existing builders specified in /etc/nix/machines get ignored: --builders "" — chef's kiss for when they're not reachable due to network connectivity. ✨

  • --profile-name name, -p name — 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're on GRUB 2, every system profile you create with this flag gets its own submenu named "NixOS - Profile name" in GRUB's boot menu, containing the current and previous configurations of that 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'". 🌸

  • --specialisation name, -c name — activates the given specialisation; when it's not specified, switching and testing will activate the base, unspecialised system. 🦋
  • --image-variant variant — selects an image variant to build from the config.system.build.images attribute of the given configuration. A list of variants gets printed if this option remains unset. 👀
  • --build-host host — instead of building the new configuration locally, use the specified host to do the build. The host needs to be accessible with ssh, and it must be able to perform Nix builds. If the --target-host option isn't set, the build gets copied back to the local machine when it's done. 🔥

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 host — specifies the NixOS target host. By setting this to anything other than an empty string, system activation happens 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 isn't explicitly specified or is empty, building takes 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.

⚠️ Heads up: nixos-rebuild honors the nixpkgs.crossSystem setting of the given configuration but disregards the true architecture of the target host. So that nixpkgs.crossSystem setting has to match the target platform or else activation will fail. 😭 fr fr, no cap.
  • --use-substitutes — when set, nixos-rebuild adds --use-substitutes to each invocation of nix copy. This only affects nixos-rebuild's behavior if --target-host or --build-host is also set. It's the moment when the target-host connection to cache.nixos.org is faster than the connection between hosts — we love a bandwidth shortcut. ⚡
  • --elevate {none,sudo,run0} — privilege-elevation method used for activation commands. Setting this option allows deploying as a non-root user. 💜

sudo prefixes commands with sudo. Additional sudo options can be passed via the NIX_SUDOOPTS environment variable.

run0 uses systemd's polkit-based elevation. Locally this runs run0 directly so the user's normal polkit agent handles any prompts. With --target-host the equivalent systemd-run --uid=0 --pipe form is used (no remote TTY is allocated). Unless --ask-elevate-password is also passed, the deploying user must be granted the polkit action org.freedesktop.systemd1.manage-units on the target host without authentication, e.g. via security.polkit.extraConfig. 🔑

  • --ask-elevate-password, -S — prompt locally for a password and feed it to the elevation method. Implies --elevate=sudo if --elevate isn't given. 🙈

For sudo this uses sudo --stdin. For run0 the command gets wrapped in polkit-stdin-agent, which registers a per-process polkit agent and answers the PAM conversation from the supplied password. The machine performing the elevation (the local host, or the target host with --target-host) must set system.tools.nixos-rebuild.enableRun0Elevation = true. --elevate=run0 --ask-elevate-password is not usable otherwise. 💀

  • --sudo — alias for --elevate=sudo. 💅
  • --ask-sudo-password — alias for --elevate=sudo --ask-elevate-password. 🎀
  • --use-remote-sudo — deprecated, use --elevate=sudo instead. she's retired ✨
  • --file path, -f path — build the NixOS system from the specified file. The file must evaluate to an attribute set, and it must contain a valid NixOS configuration at attribute attrPath. This is useful for building a NixOS system from a nix file that isn't a flake or a NixOS configuration module. 🦋

An attribute set with a valid NixOS configuration can be made using the nixos function in nixpkgs, or by importing and calling nixos/lib/eval-config.nix from nixpkgs. If specified without the --attr option, it builds the configuration from the top-level attribute set of the file. Using this option disables automatic flake detection, same as --no-flake. 👀

  • --attr attrPath, -A attrPath — build the NixOS system from a nix file and use the specified attribute path from the file specified by the --file option. If specified without the --file option, it uses system.nix in the current directory, the system-wide <nixos-system> file, or finally, /etc/nixos/system.nix. Using this option disables automatic flake detection, same as --no-flake. ⭐
  • --flake flake-uri[#name], -F 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 that exists. The flake must contain an output named nixosConfigurations.name. If name is omitted, it defaults to the current host name. 🌈
  • --no-flake — do not imply --flake if /etc/nixos/flake.nix exists. With this option it's possible to build non-flake NixOS configurations even if the current NixOS system uses flakes. 🎀
  • --diff — show the diff between the system closure in /run/current-system and the newly built system closure. (available for actions: build, boot, test, switch) 🔍

This is similar to running nix store diff-closures /run/current-system result after build. obsessed with seeing the receipts honestly.

In addition, nixos-rebuild accepts the following options from the nix commands that the tool calls. First up, the flake ones:

  • --accept-flake-config
  • --refresh
  • --impure
  • --offline
  • --no-net
  • --recreate-lock-file
  • --no-update-lock-file
  • --no-write-lock-file
  • --no-registries
  • --commit-lock-file
  • --update-input input-path
  • --override-input input-path flake-url

🔨 Builder options

And these builder besties:

  • --verbose, -v
  • --quiet
  • --log-format
  • --no-build-output, -Q
  • --no-link
  • --max-jobs, -j
  • --cores
  • --keep-going, -k
  • --keep-failed, -K
  • --fallback
  • --include, -I
  • --option
  • --repair
  • --builders
  • --print-build-logs, -L
  • --show-trace

See the Nix manual, nix flake lock --help or nix-build --help for the details. iykyk 💅

🌸 ENVIRONMENT 🌸

  • NIXOS_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. 🦋
  • NIXOS_REBUILD_SSH_DEFAULT_OPTS — replaces the built-in default ssh options (connection sharing via a private ControlMaster that is closed on exit). If empty, no default options are added. ✨
  • NIX_SUDOOPTS — additional options to be passed to sudo on the command line. 🔑
  • NIXOS_REBUILD_NO_SYSTEMD_RUN — if set, then nixos-rebuild will run without the systemd-run wrapper. 🫶

💖 FILES 💖

okay so before we get into the actual files, quick vibe check — these are the paths nixos-rebuild lowkey keeps an eye on, and knowing them is chef's kiss for understanding why it does what it does 👑

  • /etc/nixos/system.nix — if this file exists, then nixos-rebuild will use it as if the --file option was given. This allows to build a self-contained system configuration, without requiring ‘nixos’ channel. literally the "i brought my own config, thanks" energy ✨
  • /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. no cap, you can just point it at your real flake and it's fine 🫶
  • /run/current-system — a symlink to the currently active system configuration in the Nix store. that's the system you're living in right now, bestie 💅
  • /nix/var/nix/profiles/system — the Nix profile that contains the current and previous system configurations. Used to generate the GRUB boot menu. so like, this is the reason you can pick an older gen at boot and save yourself 😭🔥
ngl these four paths are the whole plot. system.nix and flake.nix are the "autodetect my config" girlies 🌸, and the other two are the "this is what's live and this is the history" girlies 🎀

👑 AUTHORS 👑

Nixpkgs/NixOS contributors — iconic collective behaviour, we love a whole community serving 🫶✨

and that's a wrap on nixos-rebuild(8), bestie!! this page came to you from nixpkgs and its date stamp is the absolutely legendary 1980-01-02 💀🎀 go forth and rebuild responsibly, mwah 💖🦋🌈

📦 where this page comes from