Installing NixOS

Updated

July 30, 2026

Installing NixOS

Goal: Install a disposable NixOS 26.05 “Yarara” lab system (VM strongly preferred), boot it, capture hardware config notes, and prepare for flake-based management in the next chapter.

Important

Do not experiment on your only daily-driver disk. Use a VM, spare machine, or spare disk. Reinstall without drama is a feature.

Why this chapter matters

Generations, rollback, modules, and firewall only become real on a host. Concepts was the package manager + language. This part is owning a machine as code—starting with a clean install.

Ops motivation: every production NixOS story begins with a first generation that boots. Install literacy (UEFI, ESP, generate-config, credentials) is how you recover when experiments go wrong.

Theory 1 — What you are installing

Piece	Role
NixOS	Linux distribution built from Nix modules
nixpkgs 26.05 “Yarara”	Package + module set baseline for this book
Installer image	Live environment to partition + install
First generation	Initial system closure after install

After install you have a bootable system. Flake ownership is the flake hosts chapter—this chapter can use installer defaults, but mentally prepare to migrate immediately.

Release identity

# after install
nixos-version
cat /etc/os-release

Confirm 26.05, not accidental unstable, when following this book’s baseline.

Theory 2 — Disposable VM emphasis

Host choice	Recommendation
VM (QEMU/KVM, UTM, VirtualBox, VMware, …)	Preferred
Spare laptop/NUC	Good
Dual-boot daily driver	Risky for learning
Cloud VM	Fine if you accept networking/SSH from the start

VM resources (practical)

Resource	Starting point
RAM	4–8 GB
Disk	40–64 GB+
CPU	2+ cores
Firmware	UEFI if available
Snapshot	Take one after first successful boot

Snapshots turn “I broke GRUB” into “restore 30 seconds.”

Networking modes (hypervisor)

Mode	Use
NAT	Simple outbound; port-forward for SSH
Bridged	LAN IP like a physical host
Host-only	Isolated lab segment

Record the mode in notes—the networking chapter needs it.

Theory 3 — UEFI vs legacy BIOS

Mode	Common loader on NixOS
UEFI	systemd-boot (often default) or GRUB EFI
BIOS/CSM	GRUB

Prefer UEFI for new labs. Note which you used—the boot and hardware chapter returns to boot loaders.

ESP requirements

Need	Typical
ESP size	512 MB–1 GB FAT32
Mount during install	`/mnt/boot`
Variables	`canTouchEfiVariables` often true on real UEFI

Theory 4 — Disk layout options

Manual (classic installer path)

Partition (ESP + root, optional swap)
Format
Mount at /mnt, ESP at /mnt/boot
nixos-generate-config --root /mnt
Edit configuration.nix
nixos-install

Disko (intro only)

Disko declares disks as code. Full Disko redesign is in the Ops and fleet part. In this chapter:

Know Disko exists
Optionally follow a simple Disko example if you already know it
Otherwise manual once is fine and educational

Do not block install on learning Disko deeply here.

Suggested simple layout (UEFI)

ESP  (vfat)  512MB–1GB   → /boot
root (ext4 or btrfs)     → /
swap (optional)

Why not exotic FS on first install?

ZFS/btrfs fancy layouts are powerful and easy to misconfigure. Prefer boring for the first bootable lab; redesign later with Disko when you understand state.

Theory 5 — `nixos-generate-config` outputs

File	Role
`hardware-configuration.nix`	Detected devices, fileSystems, initrd modules
`configuration.nix`	High-level system config (you own this)

Rules of thumb

Treat hardware-configuration.nix as machine-specific; rarely hand-merge casually
Put policy (users, services, packages) in configuration.nix / modules
Next chapter both get imported from a flake

What generate-config is good at

Captures well	Does not invent for you
Disk UUIDs	Hostname policy
Initrd modules for disks	Firewall policy
Basic boot bits	SSH keys

Theory 6 — Installer networking and time

Install needs:

Network for substitutes (unless offline media strategy)
Correct clock helps TLS

# live environment examples (names vary)
ip a
ping -c 2 1.1.1.1
timedatectl 2>/dev/null || date

Broken DNS in the live environment looks like “NixOS install is broken.”

Theory 7 — First boot mental model

After nixos-install and reboot:

bootloader → kernel+initrd → stage-1/2 → systemd → multi-user
system profile: /nix/var/nix/profiles/system
generation N is current

You can log in as root or the user you created. Prefer SSH key setup ASAP (users chapter formalizes); avoid building habits around password-only remote root.

Activation vs “files on disk”

The installed system is a closure activated into place—not a traditional unpack of a rootfs tarball only. Generations will make that concrete in the rebuild chapter.

Theory 8 — Credentials hygiene on a lab

Practice	Why
Unique lab password	Compromise isolation
Note in password manager	Labs still get attacked if exposed
Prefer host-only networking until ready	Reduce drive-by SSH noise
Snapshot before experiments	Fast recovery
Temporary `initialPassword` only	Rotate; prefer keys

Theory 9 — `system.stateVersion`

system.stateVersion = "26.05";

This is not “current release tracking.” It tells NixOS which stateful defaults to preserve for compatibility. Set it to the release you installed; read release notes before ever changing it.

Theory 10 — Minimal install config knobs

Focus during first install:

Knob	Why
Boot loader enable	Must boot
Hostname	Identity
User + wheel	Admin path
Optional SSH	Remote lab convenience
Timezone	Sanity
Experimental features	Smoother flake migration

Defer fancy services until the flake is source of truth.

Worked examples bank

Example A — Download image

Use official docs for current ISO:

https://nixos.org/download/

Pick 26.05 graphical or minimal ISO matching your arch (x86_64, aarch64).

Verify checksums when provided.

Example B — Partition sketch (sfdisk/parted-level ideas)

/dev/vda1  EFI System  FAT32  /boot
/dev/vda2  Linux root  ext4   /

Device names: vda (virtio), sda, nvme0n1—use what the live system sees (lsblk).

Example C — Generate + install skeleton

# after mounts ready
sudo nixos-generate-config --root /mnt
sudo nano /mnt/etc/nixos/configuration.nix
sudo nixos-install
# set root password when prompted

Example D — Minimal configuration knobs to set during install

{
  imports = [ ./hardware-configuration.nix ];

  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  networking.hostName = "lab";
  time.timeZone = "UTC"; # set yours

  users.users.alice = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
    # initialPassword only for offline lab convenience — rotate later
    initialPassword = "changeme";
  };

  services.openssh.enable = true; # if you want SSH into VM
  nix.settings.experimental-features = [ "nix-command" "flakes" ];

  system.stateVersion = "26.05"; # match release; do not casually change later
}

Exact options must match your installer generation—adapt from generated file rather than blind paste.

Example E — Mount checklist before generate-config

lsblk -f
findmnt /mnt
findmnt /mnt/boot
# ESP must be mounted or boot will fail later

Lab 1 — Plan and snapshot strategy

Write in ~/lab/nixos-book/host/install/NOTES.md (on the workstation):

Hypervisor / hardware choice
UEFI or BIOS
Disk size
Hostname
Username
Networking mode (NAT/bridge)
Snapshot plan

Lab 2 — Install NixOS 26.05

Boot installer ISO
Partition + format + mount
nixos-generate-config --root /mnt
Edit config: hostname, user, boot loader, optional SSH
nixos-install
Reboot into installed system
Take a VM snapshot labeled nixos-26.05-fresh-install

If install fails, journal the error class (bootloader, mount, network, disk).

Lab 3 — Post-install inventory

On the new system:

nixos-version
uname -a
lsblk -f
cat /etc/os-release
ls /etc/nixos/

Copy off-box (screenshot/scp) or retype into host NOTES.md:

nixos-version output
Disk layout
Boot loader in use
IP address if any

Lab 4 — Preserve hardware config

# on NixOS lab
sudo cp -a /etc/nixos /root/nixos-etc-backup-$(date +%F)

On workstation notes, record that the flake hosts chapter will create a flake and import hardware-configuration.nix.

Optional: already enable flakes in system config for a smoother next chapter:

nix.settings.experimental-features = [ "nix-command" "flakes" ];

Then sudo nixos-rebuild switch once if you edit on the running system.

Lab 5 — Break-glass familiarity

Without destroying the snapshot casually:

Locate boot menu / how to pick previous generation (may only have gen 1)
Confirm you can log in on console
If SSH enabled, log in from host once

Exercises

Compare minimal vs graphical ISO trade-offs for your lab.
Document exact lsblk before and after partitioning.
Practice mounting ESP incorrectly in a throwaway VM; see the failure mode (snapshot first).
List every password/key created; store only in a password manager.
Write a 10-step reinstall runbook from your real commands.
Note substitute traffic during install (why network mattered).
Identify system.stateVersion in your config; explain it to a peer.
Capture nixos-generate-config diffs if you re-run after disk changes (careful).
Time a full install; note where you waited on downloads.
Sketch Disko-shaped layout for the same partitions (no implement required).
Verify checksum of the ISO you downloaded.
Confirm experimental features enabled before the flake chapter.

Common pitfalls

Symptom	Theory
No bootable device	ESP not mounted at `/mnt/boot` or wrong firmware mode
Install can’t reach cache	Network/DNS in live env
Forgot root password	Live ISO recovery / reinstall—why snapshots matter
`hardware-configuration` wrong root UUID	Generated before final mounts
Using unstable ISO by mistake	Check 26.05 label
Daily driver install “for fun”	Restore from backup; prefer VM next time
Both GRUB and systemd-boot enabled	Loader conflict
Tiny disk	Store fills during first real use

Checkpoint

Disposable NixOS 26.05 lab boots
User + privilege path known (root/wheel)
Disk + boot mode documented
/etc/nixos inspected
VM snapshot taken (if VM)
Notes stored on workstation
Ready to migrate to a flake repo next

Further depth (this book)

Topic	Chapter
Flake as SoT	Flake-defined hosts
Generations	Rebuild modes and generations
Boot details	Boot and hardware
Disks as code	Ops part: Disko
Filesystems / state	Filesystems and state

Installing NixOS

Why this chapter matters

Theory 1 — What you are installing

Release identity

Theory 2 — Disposable VM emphasis

VM resources (practical)

Networking modes (hypervisor)

Theory 3 — UEFI vs legacy BIOS

ESP requirements

Theory 4 — Disk layout options

Manual (classic installer path)

Disko (intro only)

Suggested simple layout (UEFI)

Why not exotic FS on first install?

Theory 5 — nixos-generate-config outputs

What generate-config is good at

Theory 6 — Installer networking and time

Theory 7 — First boot mental model

Activation vs “files on disk”

Theory 8 — Credentials hygiene on a lab

Theory 9 — system.stateVersion

Theory 10 — Minimal install config knobs

Worked examples bank

Example A — Download image

Example B — Partition sketch (sfdisk/parted-level ideas)

Example C — Generate + install skeleton

Example D — Minimal configuration knobs to set during install

Example E — Mount checklist before generate-config

Lab 1 — Plan and snapshot strategy

Lab 2 — Install NixOS 26.05

Lab 3 — Post-install inventory

Lab 4 — Preserve hardware config

Lab 5 — Break-glass familiarity

Exercises

Common pitfalls

Checkpoint

Further depth (this book)

Theory 5 — `nixos-generate-config` outputs

Theory 9 — `system.stateVersion`