Using a config

You have flake.nix and configuration.nix from Ternix. This page walks through applying them to a real machine and getting back to safety if something misbehaves. Make sure flakes are enabled first (Getting started).

1. Put the files in a directory

Both files need to live together in a directory you control. A git repository is the right choice because a Nix flake only sees files that git tracks. A file you create but do not stage is invisible to the build, which is the single most common surprise for newcomers.

mkdir -p ~/nixos && cd ~/nixos
# copy flake.nix and configuration.nix into this directory
git init && git add .

/etc/nixos works too, but a personal repository is easier to version and carry between machines.

If you add a new file later and want the flake to see it before you are ready to commit, mark it with intent-to-add.

git add -N configuration.nix   # replace with whichever file you just created

This registers the path as tracked without recording its content in a commit, so the Nix evaluator picks it up on the next build.

Follow the section below that matches what Ternix generated (2a for a NixOS system, 2b for a Home Manager config, 2c for a dev shell). You may have more than one.

2a. Apply a NixOS system

The generated flake exposes your system as nixosConfigurations.nixos-host for x86_64-linux. The flake target syntax is path#name, where . means the current directory.

sudo nixos-rebuild switch --flake .#nixos-host

switch does three things. Quoting the NixOS manual ↗, it will "build the new configuration, make it the default configuration for booting, and try to realise the configuration in the running system". Two related modes give finer control.

• boot will "build the configuration and make it the boot default, but not switch to it now (so it will only take effect after the next reboot)".
• test will "build the configuration and switch the running system to it, but without making it the boot default".

Use test to try a risky change without committing it to the boot menu. If it works, run switch to keep it. If the build fails at any point, the running system is unchanged.

When a build error is hard to read, add --show-trace to get the full evaluation stack.

sudo nixos-rebuild switch --flake .#nixos-host --show-trace

2b. Apply a Home Manager config

If you generated a Home Manager output, it is exposed as homeConfigurations.user. Apply it with the standalone Home Manager command.

home-manager switch --flake .#user

Home Manager must already be installed. If it is not, see Getting started.

2c. Enter a dev shell

If you generated a devShell, you can drop into it without installing anything into your system or user profile.

nix develop

The shell exits cleanly when you close the terminal. Nothing is added to your environment permanently.

3. Rolling back

As the NixOS manual ↗ explains, "a new item is added to the menu. This allows you to easily roll back to a previous configuration if something goes wrong." You have two ways to use that.

# return the running system to the previous generation
sudo nixos-rebuild switch --rollback

Or reboot and pick an older generation from the boot menu. A generation that builds successfully but misbehaves at runtime is exactly what rollback is for. No files are lost and your store is intact.

List your system generations to see what is available.

nixos-rebuild list-generations
# or, the lower-level form
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

For Home Manager, list generations and roll back by running the activate script of an earlier one. Each line of home-manager generations ends with its store path.

home-manager generations
/nix/store/<hash>-home-manager-generation/activate

Try it in a VM first

nixos-rebuild build-vm builds a QEMU virtual machine image of the configuration without touching the running system.

nixos-rebuild build-vm --flake .#nixos-host
./result/bin/run-nixos-host-vm

The runner script is named after networking.hostName (here nixos-host), and the VM boots with its own disk, so nothing on the host changes. Of the four ways to apply a config, build-vm is the safest preview, because switch, boot, and test all touch the host while build-vm never does.

Advanced

nixos-rebuild can build for and deploy to a remote host with --target-host and --build-host, which is how many people manage servers from a laptop. The --flake flag also accepts an absolute path or a remote flake reference in place of ., so you can rebuild straight from a git URL without cloning locally first.

Before applying to a machine, nix flake check evaluates your flake and surfaces obvious errors early.

nix flake check

For a dry run that shows what would be built without activating anything, run this command.

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

Next

To pull newer package versions, update the flake inputs and rebuild, covered in Flakes. To change what is installed or configured, see Editing your config.