Skip to content

Install and bootstrap

Pick a path by physical access, SSH reachability, and OS goal (full NixOS vs Nix / Home Manager / nix-darwin on another OS). Fresh install ≠ day-2 updates.

Decision table

Situation Prefer Leaf Avoid if…
Desktop at the machine; guided UI Graphical ISO (Calamares) Graphical installer Custom disk layout, dual-boot, flake-first install, or you booted a minimal ISO
Console / minimal ISO; custom disks; learning the stack Manual: partition → /mnt → nixos-generate-config → nixos-install Manual install You only need a stock erase-disk desktop wizard
Local / boot media + declarative disks in one step disko-install (disko + nixos-install) disko Remote-only host (use nixos-anywhere); dual-boot (disko destructive modes wipe the target)
Fresh NixOS over SSH (kexec → disko → install) nixos-anywhere nixos-anywhere Day-2 deploys; Wi‑Fi-only networking; under ~1.5 GB RAM; aarch64 without custom --kexec (default image is x86_64-only)
Rack / LAN: boot installer without USB PXE / iPXE netboot, then manual (or SSH tools) Netboot and PXE No DHCP/TFTP (or HTTP) infrastructure
Share disk with another OS, or guest / build-vm Dual-boot or VM install paths Dual boot and VMs Whole-disk erase in the graphical wizard
macOS system modules nix-darwin (darwin-rebuild) nix-darwin Expecting a NixOS ISO or Linux systemd
Linux/macOS host; user env only Nix + Home Manager standalone Home Manager · standalone vs module · Nix on other distros Needing a full NixOS rootfs
Windows + WSL Nix-in-distro or NixOS-WSL WSL and foreign OS Confusing “Nix on Ubuntu-WSL” with NixOS-as-WSL
Only the Nix package manager (not NixOS) Official / Lix / Determinate installers Installers and Nix variants Treating curl installers as a NixOS ISO substitute
After bootstrap: change a running NixOS nixos-rebuild / remote deploy Rebuild switch/boot/test · Remote deploy Re-running nixos-anywhere for ordinary updates

Hub: NixOS installation. ISOs: nixos.org/download.

Failure callouts

Symptom / mistake Fix
Using nixos-anywhere for day-2 config pushes Switch to nixos-rebuild --target-host (or deploy tools under deployment and infra)
nixos-anywhere stalls / network oddities on Wi‑Fi Tool assumes wired/public/local reachability; custom --kexec if you need VPN-like networking
kexec OOM or hangs Need ≥ ~1.5 GB free RAM (excl. swap) for default kexec; see nixos-anywhere
The default kexec image only support x86_64 Pass --kexec with a matching tarball (aarch64 / custom networking)—nixos-anywhere
Live Wi‑Fi worked; first boot has no wireless Generated config often omits NM/wireless—declare networking after install (graphical / manual)
Treated “Nix on Ubuntu-WSL” as NixOS-WSL Different roots: foreign-distro Nix vs NixOS-as-WSL—WSL and foreign OS

See also

References