1---2name: nixos3description: Use when the user asks about NixOS, Nix language, flakes, nixpkgs, configuration.nix, nixos-rebuild, modules, options, overlays, derivations, mkDerivation, callPackage, home-manager, nix-darwin, devenv, packaging, cross-compilation, binary caches, garbage collection, NixOS containers, networking, firewall, systemd services, filesystems, LUKS, Wayland, X11, kernel, profiles, NixOS testing or VM tests, ISO images, Docker images, Raspberry Pi, Terraform, distributed builds, remote machines, pinning nixpkgs, rollback, generations, Nix Pills, or any topic related to configuring, packaging, deploying, or troubleshooting NixOS and the Nix ecosystem.4---56# NixOS Documentation78Complete reference for NixOS and the Nix ecosystem, auto-generated from official repositories:910- [nix.dev](https://nix.dev/) - tutorials, guides, best practices11- [NixOS Manual](https://nixos.org/manual/nixos/stable/) - from `NixOS/nixpkgs`12- [Nix Pills](https://nixos.org/guides/nix-pills/) - progressive learning series13- [Release Wiki](https://nixos.github.io/release-wiki/) - NixOS release process1415The `references/` directory contains full, unmodified documentation from those sources, updated daily.1617## How to Use18191. Identify the topic from the user's question and read the matching reference file from the tables below.202. Base answers on those files. If more detail is needed, fetch the latest docs from the raw GitHub URLs in Live Fetching.213. Distinguish between **NixOS module options** (`services.nginx.enable = true;`) and **Nix language expressions** (`pkgs.mkDerivation { ... }`).224. Show examples using current syntax (`configuration.nix` or flake-based configs). When flakes are relevant, show both the classic (channels) and flakes approach.235. For packaging, prefer the `callPackage` pattern over raw `import`.246. Beginners: start with `references/first-steps.md` or `references/nix-pills.md`. Troubleshooting: check `references/troubleshooting.md` and `references/faq.md` first. System issues: `references/nixos-administration.md`.2526## Reference Files2728### Getting Started2930| Topic | File |31|-------|------|32| Installing Nix package manager | **`references/install-nix.md`** |33| NixOS installation (USB, PXE, VirtualBox, proxy, other distro) | **`references/nixos-installation.md`** |34| First steps (ad-hoc shells, declarative shell, reproducible scripts) | **`references/first-steps.md`** |35| Upgrading NixOS | **`references/nixos-upgrading.md`** |36| Changing NixOS configuration | **`references/nixos-changing-config.md`** |37| Glossary and terminology | **`references/glossary.md`** |38| FAQ | **`references/faq.md`** |3940### Nix Language & Concepts4142| Topic | File |43|-------|------|44| Nix language tutorial | **`references/nix-language.md`** |45| Flakes (concept and usage) | **`references/flakes.md`** |46| callPackage design pattern | **`references/callpackage.md`** |47| Module system (basics and deep dive) | **`references/module-system.md`** |48| Working with local files in Nix | **`references/working-with-local-files.md`** |49| Pinning nixpkgs versions | **`references/pinning-nixpkgs.md`** |50| Nix Pills (progressive learning, 20 lessons) | **`references/nix-pills.md`** |5152### NixOS Configuration5354| Topic | File |55|-------|------|56| Configuration syntax, modularity, abstractions | **`references/nixos-config-syntax.md`** |57| Package management (declarative, ad-hoc, custom packages) | **`references/nixos-package-mgmt.md`** |58| User management | **`references/nixos-user-mgmt.md`** |59| Networking (firewall, SSH, IPv4/6, wireless, NetworkManager) | **`references/nixos-networking.md`** |60| Filesystems (LUKS, SSHFS, OverlayFS) | **`references/nixos-filesystems.md`** |61| Display server (X11, Wayland, Xfce, GPU acceleration) | **`references/nixos-display-server.md`** |62| Linux kernel configuration | **`references/nixos-linux-kernel.md`** |63| Kubernetes | **`references/nixos-kubernetes.md`** |64| Configuration profiles (minimal, graphical, headless, etc.) | **`references/nixos-profiles.md`** |6566### NixOS Administration6768| Topic | File |69|-------|------|70| Service management, logging, rollback, troubleshooting, boot problems | **`references/nixos-administration.md`** |71| Containers (declarative, imperative, networking) | **`references/nixos-containers.md`** |7273### NixOS Development7475| Topic | File |76|-------|------|77| Writing NixOS modules (options, types, assertions) | **`references/nixos-writing-modules.md`** |78| NixOS tests (writing, running, interactive) | **`references/nixos-testing.md`** |79| Building NixOS images (ISO, systemd-repart) | **`references/nixos-building-images.md`** |8081### Packaging & Build8283| Topic | File |84|-------|------|85| Packaging existing software for nixpkgs | **`references/packaging-tutorial.md`** |86| Cross-compilation | **`references/cross-compilation.md`** |8788### Tutorials8990| Topic | File |91|-------|------|92| NixOS configuration on a VM | **`references/nixos-vm-tutorial.md`** |93| Building and running Docker images | **`references/nixos-docker-tutorial.md`** |94| Building a bootable ISO image | **`references/nixos-iso-tutorial.md`** |95| Integration testing with VMs | **`references/nixos-testing-tutorial.md`** |96| Deploying NixOS with Terraform | **`references/nixos-terraform-tutorial.md`** |97| Distributed builds setup | **`references/nixos-distributed-builds.md`** |98| NixOS on Raspberry Pi | **`references/nixos-raspberry-pi.md`** |99| Provisioning remote machines | **`references/nixos-remote-machines.md`** |100| Binary cache setup | **`references/nixos-binary-cache.md`** |101102### Guides & Recipes103104| Topic | File |105|-------|------|106| Best practices | **`references/best-practices.md`** |107| Troubleshooting | **`references/troubleshooting.md`** |108| Recipes (direnv, CI, dependencies, Python env, binary cache, sharing deps) | **`references/recipes.md`** |109110### Release Process111112| Topic | File |113|-------|------|114| NixOS release process, roles, branch-off, beta, freeze | **`references/release-process.md`** |115116## Live Fetching117118When reference files are insufficient, fetch the latest docs from raw GitHub:119120### nix.dev121```122https://raw.githubusercontent.com/NixOS/nix.dev/master/source/<path>.md123```124125### NixOS Manual (nixpkgs)126```127https://raw.githubusercontent.com/NixOS/nixpkgs/master/nixos/doc/manual/<section>/<file>.md128```129130### Nix Pills131```132https://raw.githubusercontent.com/NixOS/nix-pills/master/pills/<NN>-<slug>.md133```
marceloeatworld