NixOS Documentation

Complete reference for NixOS and the Nix ecosystem, auto-generated from official repositories:

• nix.dev — tutorials, guides, best practices
• NixOS Manual — from NixOS/nixpkgs
• Nix Pills — progressive learning series
• Release Wiki — NixOS release process

The references/ directory contains full, unmodified documentation from those sources, updated daily.

Directives

• Base all answers on the official NixOS documentation in the reference files below.
• Use correct Nix language syntax (attribute sets, let-in, with, inherit, etc.).
• Distinguish between NixOS module options (services.nginx.enable = true;) and Nix language expressions (pkgs.mkDerivation { ... }).
• Show configuration examples using current NixOS syntax (configuration.nix or flake-based configs).
• When flakes are relevant, show both the classic (channels) and flakes approach if applicable.
• For packaging, prefer the callPackage pattern over raw import.

Reference Files

Identify the topic from the user's question, then read the matching reference file:

Getting Started

Topic	File
Installing Nix package manager	references/install-nix.md
NixOS installation (USB, PXE, VirtualBox, proxy, other distro)	references/nixos-installation.md
First steps (ad-hoc shells, declarative shell, reproducible scripts)	references/first-steps.md
Upgrading NixOS	references/nixos-upgrading.md
Changing NixOS configuration	references/nixos-changing-config.md
Glossary and terminology	references/glossary.md
FAQ	references/faq.md

Nix Language & Concepts

Topic	File
Nix language tutorial	references/nix-language.md
Flakes (concept and usage)	references/flakes.md
callPackage design pattern	references/callpackage.md
Module system (basics and deep dive)	references/module-system.md
Working with local files in Nix	references/working-with-local-files.md
Pinning nixpkgs versions	references/pinning-nixpkgs.md
Nix Pills (progressive learning, 20 lessons)	references/nix-pills.md

NixOS Configuration

Topic	File
Configuration syntax, modularity, abstractions	references/nixos-config-syntax.md
Package management (declarative, ad-hoc, custom packages)	references/nixos-package-mgmt.md
User management	references/nixos-user-mgmt.md
Networking (firewall, SSH, IPv4/6, wireless, NetworkManager)	references/nixos-networking.md
Filesystems (LUKS, SSHFS, OverlayFS)	references/nixos-filesystems.md
Display server (X11, Wayland, Xfce, GPU acceleration)	references/nixos-display-server.md
Linux kernel configuration	references/nixos-linux-kernel.md
Kubernetes	references/nixos-kubernetes.md
Configuration profiles (minimal, graphical, headless, etc.)	references/nixos-profiles.md

NixOS Administration

Topic	File
Service management, logging, rollback, troubleshooting, boot problems	references/nixos-administration.md
Containers (declarative, imperative, networking)	references/nixos-containers.md

NixOS Development

Topic	File
Writing NixOS modules (options, types, assertions)	references/nixos-writing-modules.md
NixOS tests (writing, running, interactive)	references/nixos-testing.md
Building NixOS images (ISO, systemd-repart)	references/nixos-building-images.md

Packaging & Build

Topic	File
Packaging existing software for nixpkgs	references/packaging-tutorial.md
Cross-compilation	references/cross-compilation.md

Tutorials

Topic	File
NixOS configuration on a VM	references/nixos-vm-tutorial.md
Building and running Docker images	references/nixos-docker-tutorial.md
Building a bootable ISO image	references/nixos-iso-tutorial.md
Integration testing with VMs	references/nixos-testing-tutorial.md
Deploying NixOS with Terraform	references/nixos-terraform-tutorial.md
Distributed builds setup	references/nixos-distributed-builds.md
NixOS on Raspberry Pi	references/nixos-raspberry-pi.md
Provisioning remote machines	references/nixos-remote-machines.md
Binary cache setup	references/nixos-binary-cache.md

Guides & Recipes

Topic	File
Best practices	references/best-practices.md
Troubleshooting	references/troubleshooting.md
Recipes (direnv, CI, dependencies, Python env, binary cache, sharing deps)	references/recipes.md

Release Process

Topic	File
NixOS release process, roles, branch-off, beta, freeze	references/release-process.md

Live Fetching

When reference files are insufficient, fetch the latest docs from raw GitHub:

nix.dev

https://raw.githubusercontent.com/NixOS/nix.dev/master/source/<path>.md

NixOS Manual (nixpkgs)

https://raw.githubusercontent.com/NixOS/nixpkgs/master/nixos/doc/manual/<section>/<file>.md

Nix Pills

https://raw.githubusercontent.com/NixOS/nix-pills/master/pills/<NN>-<slug>.md

Strategy

1. Identify the topic from the user's question.
2. Read the matching reference file from the tables above.
3. Answer with correct Nix syntax and configuration.nix / flake.nix examples.
4. If more detail is needed, fetch from the corresponding raw GitHub URL.
5. For beginners, recommend starting with references/first-steps.md or references/nix-pills.md.
6. For troubleshooting, check references/troubleshooting.md and references/faq.md first.
7. For NixOS system issues, check references/nixos-administration.md.

Quick Reference

Config file location

/etc/nixos/configuration.nix (classic) or flake.nix (flakes)

Rebuild system

sudo nixos-rebuild switch          # apply config
sudo nixos-rebuild test            # apply without adding to bootloader
sudo nixos-rebuild build           # build only
sudo nixos-rebuild boot            # apply on next boot

Nix shell (ad-hoc packages)

nix-shell -p python3 git vim       # classic
nix shell nixpkgs#python3 nixpkgs#git  # flakes

Nix develop (dev environment)

nix develop                        # from flake.nix devShell
nix-shell                          # from shell.nix

Search packages

nix search nixpkgs firefox
# or https://search.nixos.org/packages

Garbage collection

nix-collect-garbage -d             # delete all old generations
nix store gc                       # flakes equivalent
sudo nix-collect-garbage -d        # also clean system profiles

Flake basic structure

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  };
  outputs = { self, nixpkgs }: {
    nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [ ./configuration.nix ];
    };
  };
}

NixOS module syntax

{ config, pkgs, ... }:
{
  services.nginx.enable = true;
  environment.systemPackages = with pkgs; [ vim git firefox ];
  networking.firewall.allowedTCPPorts = [ 80 443 ];
  users.users.myuser = {
    isNormalUser = true;
    extraGroups = [ "wheel" "networkmanager" ];
  };
}