Commands and scripts

A working flake is only half the story. The other half is the handful of commands you run to apply it, update it, inspect it, and keep the store tidy. This page collects those commands in one place so you have a dense reference to come back to, along with a few small scripts you can copy. Everything here assumes a Ternix layout with a flake.nix exposing nixosConfigurations.nixos-host for x86_64-linux, and optionally homeConfigurations.user.

The flake target syntax is path#name, where . is the current directory. Run these from the directory that holds your flake.nix unless a command says otherwise.

Rebuilding the system

nixos-rebuild builds your configuration and decides how far to apply it. The subcommand picks the level of commitment, from a throwaway build to a permanent switch.

# build, activate now, and set as the boot default
sudo nixos-rebuild switch --flake .#nixos-host
 
# build and set as boot default, but do not activate until reboot
sudo nixos-rebuild boot --flake .#nixos-host
 
# activate now without touching the boot menu, good for risky changes
sudo nixos-rebuild test --flake .#nixos-host
 
# build only, leaving a ./result symlink, no activation
nixos-rebuild build --flake .#nixos-host
 
# evaluate and show what would build, without building anything
nixos-rebuild dry-build --flake .#nixos-host
 
# build a throwaway VM of this config to test it in isolation
nixos-rebuild build-vm --flake .#nixos-host
./result/bin/run-*-vm
 
# return the running system to the previous generation
sudo nixos-rebuild switch --rollback
 
# add --show-trace when an evaluation error is hard to read
sudo nixos-rebuild switch --flake .#nixos-host --show-trace

nixos-rebuild can also build for and deploy to another machine over SSH. --target-host is where the configuration is activated, and --build-host is where the heavy compilation happens, which lets a laptop drive a server.

# build locally, activate on a remote host
sudo nixos-rebuild switch --flake .#nixos-host \
  --target-host root@server.example.com
 
# build on the remote host too, so the laptop stays idle
sudo nixos-rebuild switch --flake .#nixos-host \
  --target-host root@server.example.com \
  --build-host root@server.example.com

Working with flakes

These commands read and change the flake itself rather than your system. flake.lock pins every input to an exact revision, and the update commands are how you move those pins forward.

# show inputs, the lock state, and the resolved revisions
nix flake metadata
 
# list the outputs this flake exposes, such as nixosConfigurations
nix flake show
 
# bump every input to its latest revision and rewrite flake.lock
nix flake update
 
# bump a single input only, leaving the rest pinned
nix flake update nixpkgs
 
# evaluate every output and run checks, surfacing errors early
nix flake check
 
# create or refresh flake.lock without changing anything else
nix flake lock

Searching and inspecting

Before you add a package or change an option, it helps to see what exists and what a value currently resolves to. nix search queries package names and descriptions, while the evaluation commands read your built configuration.

# search nixpkgs for packages matching a term
nix search nixpkgs ripgrep
 
# print the current value, type, and description of an option
nixos-option services.openssh.enable
 
# read any config path straight out of your flake
nix eval .#nixosConfigurations.nixos-host.config.networking.hostName
 
# list the packages in system PATH as evaluated by the flake
nix eval .#nixosConfigurations.nixos-host.config.environment.systemPackages

For interactive poking, nix repl lets you load the flake and tab-complete your way through the configuration tree.

nix repl
# inside the repl
:lf .
nixosConfigurations.nixos-host.config.networking.firewall.allowedTCPPorts

When you want to understand why something is in your closure or how big it is, these two answer it.

# explain why one store path depends on another
nix why-depends .#nixosConfigurations.nixos-host.config.system.build.toplevel nixpkgs#openssl
 
# show the closure size of a path, -S for total size, -h for human units
nix path-info -Sh ./result

Building and running ad hoc

You do not have to edit your config to try a package. The nixpkgs#name reference pulls a single package from the registry, and these commands build it, run it, or drop it into a temporary shell.

# build a flake output and leave a ./result symlink
nix build .#nixosConfigurations.nixos-host.config.system.build.toplevel
 
# run a package once without installing it
nix run nixpkgs#hello
 
# open a shell with packages on PATH, gone when you exit
nix shell nixpkgs#ripgrep nixpkgs#fd
 
# enter the dev shell defined by a flake
nix develop

Generations and rollback

Every switch or boot records a generation, which is a snapshot you can return to. Listing them shows what the boot menu offers, and rollback walks you back one step at a time.

# list system generations with dates and changes
nix profile history --profile /nix/var/nix/profiles/system
 
# the older nix-env form, still works and shows the same profile
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
 
# roll the running system back to the previous generation
sudo nixos-rebuild switch --rollback

Home Manager keeps its own generation list, separate from the system profile.

# list Home Manager generations with their store paths
home-manager generations
 
# roll back by running the activate script of an earlier generation
/nix/store/<hash>-home-manager-generation/activate

Garbage collection and disk space

Old generations and unreferenced build outputs pile up in /nix/store. Collecting garbage frees them, and store optimisation deduplicates identical files with hard links to reclaim more.

# delete all unreferenced paths and every old generation
sudo nix-collect-garbage -d
 
# keep recent generations, delete only those older than 14 days
sudo nix-collect-garbage --delete-older-than 14d
 
# hard-link identical files in the store to save space
nix store optimise
 
# collect garbage using the newer command, respects gc roots
nix store gc

Running nix-collect-garbage -d removes the rollback targets in the boot menu, so keep a known-good generation if you are mid-change.

Useful helper scripts

Each of these is a small standalone script. Save it somewhere on your PATH, make it executable with chmod +x, and run it from inside your flake directory. The set -euo pipefail line makes the script stop on the first error instead of plowing ahead.

A rebuild-and-commit script applies the system and records the working tree only after the build succeeds, so your git history never points at a configuration that failed to build.

#!/usr/bin/env bash
set -euo pipefail
 
# apply the system first, abort the commit if it fails
sudo nixos-rebuild switch --flake .#nixos-host
 
# stage and commit, with a message from the argument or a default
msg="${1:-rebuild $(date +%Y-%m-%d)}"
git add -A
git commit -m "$msg"

An update script bumps the flake inputs and then does a test activation, which tries the new packages without writing them to the boot default. If the test is good you run your switch afterward.

#!/usr/bin/env bash
set -euo pipefail
 
# move every input forward and test the result without committing to boot
nix flake update
sudo nixos-rebuild test --flake .#nixos-host
 
echo "test activation done, run a switch when you are happy with it"

A cleanup script reclaims disk space by collecting old generations and then optimising the store. The --delete-older-than window keeps a couple of weeks of rollback targets.

#!/usr/bin/env bash
set -euo pipefail
 
# drop generations older than two weeks, then dedup the store
sudo nix-collect-garbage --delete-older-than 14d
nix store optimise
 
echo "store cleaned and optimised"

Turning these into aliases

Typing the full --flake .#nixos-host every time gets old. Once a command earns its place in your routine, give it a short name. A shell alias in your Home Manager config works for the one-liners.

programs.bash.shellAliases = {
  rebuild = "sudo nixos-rebuild switch --flake .#nixos-host";
  update = "nix flake update && sudo nixos-rebuild test --flake .#nixos-host";
};

For the multi-step scripts above, a Justfile in your flake directory keeps them versioned next to the config and documents itself with just --list. Either approach beats memorising flags.

Using a config walks through applying these rebuild commands to a real machine for the first time.
Flakes covers the update and lock workflow in depth, including how flake.lock pins inputs.
Editing your config explains the options and modules you inspect with nixos-option and nix eval.
Getting started has the one-time setup that enables flakes and the nix commands used here.