nixos-anywhere

Setting up a new machine is time-consuming, and becomes complicated when it needs to be done remotely. If you’re installing NixOS, the nixos-anywhere tool allows you to pre-configure the whole process including:

• Disk partitioning and formatting
• Configuring and installing NixOS
• Installing additional files and software

You can then initiate an unattended installation with a single CLI command. Since nixos-anywhere can access the new machine using SSH, it’s ideal for remote installations.

Once you have initiated the command, there is no need to ‘babysit’ the installation. It all happens automatically.

You can use the stored configuration to repeat the same installation if you need to.

Overview

If you have machines on a mix of platforms, you’ll need a common installation solution that works anywhere. nixos-anywhere is ideal in this situation.

nixos-anywhere can be used equally well for cloud servers, bare metal servers such as Hetzner, and local servers accessible via a LAN. You can create standard configurations, and use the same configuration to create identical servers anywhere.

You first create Nix configurations to specify partitioning, formatting and NixOS configurations. Further options can be controlled by a flake and by run-time switches.

Once the configuration has been created, a single command will:

• Connect to the remote server via SSH
• Detect whether a NixOS installer is present; if not, it will use the Linux kexec tool to boot into a Nixos installer.
• Use the disko tool to partition and format the hard drive
• Install NixOS
• Optionally install any Nix packages and other software required.
• Optionally copy additional files to the new machine

It’s also possible to use nixos-anywhere to simplify the installation on a machine that has no current operating system, first booting from a NixOS installer image. This feature is described in the how-to guide. It’s useful because you can pre-configure your required software and preferences, and build the new machine with a single command.

Important Note: Never use a production server as the target. It will be completely overwritten and all data lost. This tool should only be used for commissioning a new computer or repurposing an old machine once all important data has been migrated.

Usage

nixos-anywhere [options] [<ssh-host>]

Examples:

• Install using a flake:

nixos-anywhere --flake .#my-machine

• Install to a custom SSH host and port:

nixos-anywhere --target-host 192.168.1.10 --ssh-port 2222 --flake .#my-machine

• Run a dry VM test:

nixos-anywhere --vm-test --flake .#my-machine

---

Options

Option	Description	Notes / Default
-f, --flake <flake_uri>	Set the flake to install the system from. Supports variants like .#nixosConfigurations.mymachine.config.virtualisation.vmVariant.	Required unless using --store-paths.
--target-host <ssh-host>	Set the SSH target host to deploy onto.
-i <identity_file>	Select which SSH private key to use.
-p, --ssh-port <ssh_port>	Set the SSH port.	Default: 22
--ssh-option <ssh_option>	Set one SSH option. Can be repeated.	Example: --ssh-option UserKnownHostsFile=./known_hosts
-L, --print-build-logs	Print full build logs.
--env-password	Use password from SSHPASS environment variable for ssh-copy-id.
-s, --store-paths <disko-script> <nixos-system>	Set store paths directly, bypassing flake.
--kexec <path>	Use a custom kexec tarball to bootstrap NixOS.
--kexec-extra-flags	Extra flags for kexec, e.g., --no-sync.
--ssh-store-setting <key> <value>	SSH store settings appended to store URI. Value must be URI encoded.	Example: compress=true
--post-kexec-ssh-port <ssh_port>	SSH port to use after kexec.	Default: 22
--copy-host-keys	Copy /etc/ssh/ssh_host_* from host to installation.
--extra-files <path>	Recursively copy contents of <path> to / on the new system.	Ownership defaults to root unless --chown is specified.
--chown <path> <ownership>	Change ownership recursively. Can be repeated.	Recommend uid:gid.
--disk-encryption-keys <remote_path> <local_path>	Copy or pipe encryption keys for disks. Can be repeated.	Runs after kexec but before installation.
--no-substitute-on-destination	Disable --substitute-on-destination during nix-copy. Implies --no-use-machine-substituters.
--no-use-machine-substituters	Do not copy machine substituters into installer environment.
--debug	Enable debug output.
--show-trace	Show nix build traces.
--option <key> <value>	Pass a Nix option to every nix command.
--from <store-uri>	URL of source Nix store to copy nixos and disko closure from.
--build-on-remote	Build the closure on the remote machine instead of locally.
--vm-test	Build the system and test disk configuration inside a VM.
--generate-hardware-config <backend> <path>	Generate a hardware-configuration.nix file. Backend can be nixos-facter or nixos-generate-config.
--phases <phases>	Comma-separated list of phases: kexec,disko,install,reboot.	Default: all phases
`—disko-mode <disko	mount	format>`	Set disko mode: disko (destroy/create/mount), mount, or format.	Default: disko
--no-disko-deps	Only upload disko script, skip dependencies.	Useful for low-RAM machines.
`—build-on <auto	remote	local>`	Where to build the system closure.	Default: auto

Phases

nixos-anywhere installation can be broken down into phases:

1. kexec – Boot into the NixOS installer using kexec.
2. disko – Unmount and destroy filesystems, then create and mount new ones.
3. install – Install the NixOS system.
4. reboot – Unmount filesystems, export ZFS pools, reboot the machine.

Each phase can be skipped or customized using the --phases option.

Disk Modes

The --disko-mode controls how disks are handled:

Mode	Description
disko	Default: destroy, create, and mount partitions.
format	Only format partitions.
mount	Only mount existing partitions.

Example Full Command

nixos-anywhere \
  --flake .#my-machine \
  --target-host 192.168.1.10 \
  --ssh-port 2222 \
  --extra-files ./custom-files \
  --chown /etc/myconfig 1000:1000 \
  --disk-encryption-keys /root/keyfile ./localkey \
  --print-build-logs

This will deploy NixOS to the target host, copying custom files, setting ownership, handling disk encryption keys, and printing build logs.