A NixOS learning roadmap: foundations, Flakes, user configuration, and beyond

Module one: foundational concepts#

1.1 What NixOS is & its design philosophy

• Declarative vs imperative system management
• What functional package management means
• How /nix/store works
• Fundamental differences from Arch/Debian

Resources:

• NixOS About Page
• How Nix Works
• Nix: Under the Hood (YouTube)

1.2 Nix language basics

• Basic types: string, int, bool, list, attrset
• let ... in、with、import
• Function syntax (x: x + 1)
• Path types and string interpolation

Resources:

• Nix Language Basics (official)
• Nix Pills Ch.4-6
• nix.dev — the official Nix documentation site, useful for reading tutorials alongside reference manuals.

Building the documentation locally

In a trusted checkout of the nix.dev source, first choose the development environment appropriate to the repository version, then run the build:

cd /path/to/nix.dev
direnv allow    # 阅读 .envrc 后授权；或使用仓库支持的 nix-shell
make html
xdg-open build/html/index.html

Use the checkout's README/Makefile as the authority for the build entry point and output path.

Module two: system configuration#

2.1 Core structure of configuration.nix

• environment.systemPackages
• services.* enables system services
• users.users.* manages users
• networking, time, i18n basic configuration
• Differences between nixos-rebuild switch / boot / test

Resources:

• NixOS Manual: Configuration
• NixOS Options Search — an essential tool for finding all available options
• MyNixOS — browse options visually

2.2 Package management

• nix search、nix-env(legacy)vs declarative
• How to enable unfree packages
• Introduction to overlays: overriding/modifying existing packages
• Temporary environments with nix-shell -p

Resources:

• Nixpkgs Search
• NixOS Manual: Package Management
• Nixpkgs Manual: Overlays

2.3 Generations & rollbacks

• Successful builds and profile switches produce recoverable configuration generations; evaluation checks do not create or activate a generation
• Booting multiple generations through GRUB
• Cleaning up old generations with nix-collect-garbage

Resources:

• NixOS Manual: Rollback

Module three: flakes (common workflows)#

3.1 What flakes are

• Problems they solve (reproducibility and the drawbacks of nix-channel)
• Structure of flake.nix: inputs / outputs
• Version pinning with flake.lock

3.2 Enabling flakes & migration

• Enable experimental features in configuration.nix
• Build with nixos-rebuild switch --flake .#workstation
• Manage configurations for multiple machines

Resources:

• Flakes Introduction (nix.dev)
• Zero to Nix: Flakes
• Flakes aren't real (blog post; read critically)

Module four: Home Manager#

4.1 Introduction to Home Manager

• The boundary between system and user configuration
• Standalone mode vs NixOS module mode
• Basic structure of home.nix

4.2 Common uses

• Managing dotfiles (.zshrc, nvim, git, etc.)
• Configure applications directly with programs.*
• Declarative symlinks with home.file.*

Resources:

• Home Manager Manual
• Home Manager Options Search or MyNixOS HM options
• nix-community/home-manager (GitHub)

Module five: development environments#

5.1 nix-shell & nix develop

• Writing shell.nix
• The flake.nix devShells output
• Integration with direnv (use flake / use nix)

5.2 Language ecosystems

• Python: python3.withPackages and the boundaries between uv and nix
• Rust: fenix / rust-overlay
• C/C++: pkgs.mkShell + stdenv

Resources:

• nix.dev: Dev Environments
• nix-direnv (GitHub)
• nix-community/fenix — Rust toolchain

Module six: advanced topics (as needed)#

Recommended learning order#

模块一 → 模块二 → 模块三（Flakes）
                ↓
           模块四（Home Manager）
                ↓
           模块五（Dev Env）
                ↓
        模块六（按项目需求选）

General resources#

• zero-to-nix.com — the most approachable starting point
• nix.dev — official Nix tutorials and references
• Nixpkgs GitHub — learn how to write Nix by reading the source directly
• awesome-nix — a collection of community resources
• NixOS Discourse — the best forum for asking questions and finding examples
• NixOS Wiki — smaller than ArchWiki, but growing

What to verify as you learn#

Start by connecting /nix/store, the Nix language, and system configuration. Then understand flake input pinning and Home Manager's user-level boundaries before learning development environments, ARM, CI, cross-compilation, and secrets as projects require them. build only builds, test activates without setting the boot default, boot sets the next boot, and switch activates immediately and sets the default; verify these stages separately. Third-party tutorials and opinions retain their original links in the resources, but they do not replace the options and source code for your currently pinned version.