nixos-rebuild¶

Overview¶

nixos-rebuild is the primary CLI for applying a NixOS system configuration: it evaluates and builds a new system generation, optionally updates the boot default, and optionally activates the live machine. Activation goes through switch-to-configuration in the built system closure.

From NixOS 25.11, the default implementation is nixos-rebuild-ng (Python rewrite of the classic Bash script); the on-PATH name stays nixos-rebuild. From 26.05 onward the Bash implementation is removed, system.rebuild.enableNg must not be set, and all switchable systems use the Python rewrite.

This page is the frontend / tooling view—how you invoke the CLI, what it reads, and how it relates to alternate surfaces. For operational semantics of each action (switch / boot / test / …), root/user-service caveats, and activation ordering, see nixos-rebuild actions.

Details¶

Implementation (25.11 / 26.05)¶

Release	Behavior
Before 25.11	Bash `nixos-rebuild` by default; opt into ng via `system.rebuild.enableNg = true`
25.11+	`nixos-rebuild-ng` is default; same command name on `$PATH`
26.05+	Bash frontend removed; do not set `system.rebuild.enableNg`

The ng rewrite preserves the same subcommands and flags documented in nixos-rebuild(8); release notes call out removals (for example deprecated --fast in favor of --no-reexec). When docs or scripts mention flag renames, check the man page for your NixOS version.

Config inputs¶

By default the tool picks a config from the deploying machine:

/etc/nixos/configuration.nix — channel-style single file (classic layout)
/etc/nixos/flake.nix — when present, treated like passing --flake (automatic flake detection)

Overrides:

Flag	Use
`--file path` / `--attr attr`	Evaluate a specific `.nix` file and attribute instead of `/etc/nixos/configuration.nix`
`--flake flake-uri[#name]`	Explicit flake URL and optional `nixosConfigurations` name
`--no-flake`	Skip automatic flake detection even if `flake.nix` exists under `/etc/nixos`

With flakes, the flake must export nixosConfigurations.<name>; omitting #name defaults to the current hostname. See nixosConfigurations (flakes).

Remote deploy usually evaluates from the operator’s tree (flake checkout or -I nixos-config=…), not whatever happens to sit in the target’s /etc/nixos—see Remote deploy.

Actions (summary)¶

One required verb per invocation. This table is the frontend cheat sheet; semantics, warnings, and edge cases live on the operations page.

Action	Build	Boot default	Activate now
`switch`	yes	yes	yes
`boot`	yes	yes	no
`test`	yes	no	yes
`build`	yes	no	no

Related helpers on the same CLI: dry-build, dry-activate, repl, build-vm, build-image, list-generations, --rollback. Root (or elevation via --elevate / --sudo) is required for actions that activate or change the boot default; plain build does not need root.

Re-exec¶

Unless --no-reexec is set, nixos-rebuild first builds config.system.build.nixos-rebuild from the target config and execs into that binary so the running tool matches the generation being applied. Skip re-exec when cross-architecture deploy would fail with “Exec format error” (common with --target-host / --build-host); details on Remote deploy.

Remote and elevation¶

SSH flags split where builds run from where activation runs:

Flag	Role
`--build-host user@host`	Build on remote; copy closure back if no `--target-host`
`--target-host user@host`	Activate on remote instead of locally

Non-root SSH users need elevation on the target: --elevate={none,sudo,run0} (aliases --sudo, --ask-sudo-password / --ask-elevate-password). Prefer these over the deprecated --use-remote-sudo. Full flag matrix and NIX_SSHOPTS: Remote deploy.

Choosing a frontend¶

All paths below still end in the same activation model (switch-to-configuration on a built system closure). They differ in who runs the CLI, UX, and fleet scale—not in what “switch” means on the machine.

Surface	When to prefer it
`nixos-rebuild`	Official manual path; scripts, docs, and modules assume it; single-host or ad hoc `--target-host`
nh	One ergonomic CLI across NixOS, Home Manager, and nix-darwin; pre-switch diffs and progress; still drives rebuild/activation, not a new model (adjacent-tools detail)
`nixos-rebuild --build-host` / `--target-host`	Few remotes, same verbs as local; no inventory file
Colmena	Many-node hive: tags, parallel apply, shared defaults
deploy-rs	Flake `deploy.nodes` / profiles; CI-oriented activation with magic rollback

Fleet tools are cousins, not replacements: they orchestrate SSH/build/copy and call into the same switch/boot/test semantics. Install-time remote provisioning (not ongoing rebuild) is nixos-anywhere.

Examples¶

Channel-style host (root shell recommended for activate verbs):

sudo -i
nixos-rebuild switch
nixos-rebuild boot      # next reboot only
nixos-rebuild test      # activate now; reboot undoes boot default

Flake on the same machine (#name optional when it matches hostname):

sudo nixos-rebuild switch --flake /etc/nixos
sudo nixos-rebuild switch --flake .#myhost

Non-default config path (evaluate from a checkout, not /etc/nixos):

nixos-rebuild switch --file ~/configs/desktop.nix --attr machine
nixos-rebuild switch --flake git+file:///home/user/nixos#laptop

Force classic file mode when a flake also exists:

sudo nixos-rebuild switch --no-flake

Build-only check (no root):

nixos-rebuild build
nixos-rebuild build --flake .#myhost
nixos-rebuild dry-build --flake .

Remote activate (operator machine → target); see Remote deploy for cross-build and --no-reexec:

nixos-rebuild switch --flake .#hostname --target-host user@host --elevate=sudo