nixos-btw

NixOS BTW: NixOS, Nix, and Flakes Administration

Administer NixOS without falling back into imperative distro muscle memory. NixOS is declarative, functional, and atomic: the system is a value computed from a configuration, every change becomes a new immutable generation in /nix/store, and rollbacks are a bootloader entry away. This skill keeps that model intact, then layers in the practical stack: channels vs flakes, nixos-rebuild vs nix CLI, home-manager, nix-darwin, store hygiene, overlays, module writing, secrets, and the Determinate Nix and Lix lanes.

The places NixOS breaks are NixOS-shaped: channel drift, flake input staleness, garbage collection that nukes a needed derivation, overlays fighting, nix-env -i poisoning the user profile, hardware modules missing, or people treating /etc/nixos/configuration.nix like a normal Linux config file.

Why people run it. Atomic upgrades and rollbacks, bit-for-bit reproducible systems, disposable dev shells, fleet-wide configuration without a separate config-management tool, and a single language for a workstation, a server, a container image, a NixOS VM, and a macOS laptop via nix-darwin.

Versions worth pinning (verified May 2026):

Pin versions only when they shape compatibility or troubleshooting. For ordinary package work, trust the live channel or flake lock over a stale table.

| Component | Version or date | Why it matters | |-----------|-----------------|----------------| | NixOS stable | 25.11 "Xantusia" (Nov 2025) | current stable, maintained until 2026-06-30 | | NixOS upcoming | 26.05 "Yarara" (May 2026) | next release; do not target yet for production | | Nix (CLI / daemon) | 2.33 (Dec 2025) | stable upstream; 2.32 introduced skip-substitutable-downloads | | nixos-rebuild-ng | default in 25.11 | Python rewrite of nixos-rebuild, default for new installs | | home-manager | release-25.11 (Nov 2025) | matches NixOS 25.11; unstable tracks nixos-unstable | | nix-darwin | tracks nixpkgs 25.11 and master | active macOS module system (Intel + Apple Silicon) | | Determinate Nix | downstream, flakes-on by default | validated distribution; parallel eval, lazy trees | | Lix | fork of Nix | compatibility-focused fork; Meson build, improved errors | | Kernel default for 25.11 | Linux 6.12 LTS | default linuxPackages; linuxPackages_latest tracks mainline (6.17 at 25.11 release, not LTS) |

When to use

• NixOS system administration: configuration.nix, modules, options, imports, and /etc/nixos workflow
• Flake work: flake.nix, flake.lock, inputs, outputs, nix flake update, nix flake check
• nixos-rebuild flow: switch, test, boot, dry-activate, build-vm, and rollback
• Channels, pinning, and input management: nix-channel, nix registry, npins, niv, flake inputs
• home-manager (standalone, NixOS module, or nix-darwin module) for user-level declarative config
• nix-darwin on macOS: declarative system config, Homebrew integration, LaunchDaemons
• Nix store and derivations: nix-store, nix store, GC roots, nix-collect-garbage, optimise-store
• Dev environments: nix-shell, nix develop, shell.nix, default.nix, direnv with nix-direnv
• Overlays, overrides, and package customisation: overlays, overrideAttrs, override, pin patches
• Writing NixOS modules: options, config, assertions, conditionals, imports, mkMerge, mkForce
• Secrets management: sops-nix, agenix, nix-sops, ragenix, activation-time decryption
• Declarative disks and filesystems: disko, btrfs layouts, LUKS, ZFS, impermanence patterns
• Remote installs and imaging: nixos-anywhere, nixos-install, nixos-generate, SD images, ISO images
• Hardware enablement: nixos-hardware profiles, firmware, kernel choice, GPU drivers
• Unfree and insecure packages: allowUnfree, permittedInsecurePackages, NIXPKGS_ALLOW_*
• Boot and generations: systemd-boot vs GRUB, kernel selection, nix-env --list-generations, boot entries
• Garbage collection strategy: retention, GC roots, nix.gc.automatic, auto-optimise-store
• Determinate Nix lane: Determinate installer, flakes-on-by-default, enterprise backports
• Lix lane: fork-specific behavior, coexistence, and migration notes
• Integration with Docker, Kubernetes, and CI: nix build, image outputs, cachix, attic

When NOT to use

• Arch or CachyOS administration - use arch-btw
• Debian, Ubuntu, Mint, or Pop!_OS administration - use debian-ubuntu
• Fedora, RHEL, CentOS Stream, Rocky, or Alma administration - use rhel-fedora
• Kali Linux and offensive-tool distros - use kali-linux
• Shell syntax, quoting, or portability outside Nix expressions - use command-prompt
• Docker, Podman, image builds, or container runtime issues - use docker
• Kubernetes cluster or manifest work - use kubernetes
• Fleet-wide non-Nix Linux configuration via playbooks - use ansible
• Terraform or OpenTofu infrastructure code - use terraform
• CI/CD pipeline design for Nix-based builds (cachix push, build farm, pipeline stages) - use ci-cd
• Offensive or privesc testing - use lockpick
• Defensive hardening and vuln review - use security-audit
• OPNsense or pfSense appliance work - use firewall-appliance

AI Self-Check

Before returning NixOS or Nix commands, verify:

• [ ] Lane identified: NixOS install, Nix on non-NixOS Linux, Nix on macOS (nix-darwin or plain Nix), WSL, Determinate Nix, or Lix. Advice diverges fast.
• [ ] Channels vs flakes decided: confirm which the user has before prescribing nix-channel, nixos-rebuild --flake, or nix flake update. Mixing without intent creates channel-lock drift.
• [ ] Flake status is current: flakes remain nominally experimental on upstream Nix but are enabled by default on Determinate Nix; recommend enabling experimental-features = nix-command flakes where the user is already using flakes.
• [ ] nix-env -i is not the answer: installing into the per-user profile hides state from configuration.nix and breaks reproducibility. Use declarative environment.systemPackages, home.packages, or an ad-hoc nix shell instead.
• [ ] No partial upgrade advice: on flakes-based systems, do not bump a single input without running nixos-rebuild --flake after; on channels, do not change only nixos without updating dependent channels too.
• [ ] Rebuild verb is intentional: switch, test, boot, dry-activate, build-vm, and build differ. test does not persist the boot entry; boot does not activate now; switch does both.
• [ ] Known-good generation preserved: never remove the last known-good generation, and never nix-collect-garbage -d on a system that just booted a new generation without verifying the new one survives a reboot.
• [ ] GC roots respected: dev shells, direnv caches, and CI artifacts often hold GC roots. Do not recommend aggressive GC without checking nix-store --gc --print-roots first.
• [ ] Unfree / insecure gates named explicitly: set nixpkgs.config.allowUnfree = true; or allowUnfreePredicate, and list insecure packages under permittedInsecurePackages. Do not default to NIXPKGS_ALLOW_UNFREE=1 as the permanent answer.
• [ ] Hardware module present: for fresh installs, hardware-configuration.nix must be regenerated with nixos-generate-config and not hand-edited for filesystem UUIDs. For laptops, check nixos-hardware profile.
• [ ] Kernel and initrd coherence: boot.kernelPackages, initrd modules, filesystems, and bootloader agree. Do not casually swap kernels on a system with ZFS, NVIDIA, or custom out-of-tree modules.
• [ ] Module fields real: options named in advice exist in the version of nixpkgs the user has. options graveyards drift between 23.11, 24.05, 24.11, 25.05, and 25.11 - verify against the nixpkgs tag the user pinned.
• [ ] Secrets not put in the store: anything under ./secret.age, ./sops.yaml, or similar must be decrypted at activation time