Home Manager and flake layout

Updated

July 30, 2026

Home Manager and flake layout

This part of the standalone NixOS book is organized by topic (normal book chapters), not by calendar day.

Read chapters in order within the part when learning; skip or skim freely when using the book as a reference.

Baseline: NixOS / nixpkgs 26.05, flakes, modern nix CLI, Home Manager as a NixOS module.

What this part is for

You already own a host from a flake (nixosConfigurations). That is necessary and insufficient for a maintainable personal platform. This part covers the shape of a multi-concern flake and the user plane:

Concern Chapters
Repo layout that scales past one file Flake repository layout
Pins you can explain and revert Lock file discipline
User environment as NixOS module Home Manager on NixOS
Dotfiles, XDG, store-backed files Home files and XDG
User systemd units and timers Home Manager user services
Project toolchains without profile bloat direnv and project shells
Multi-output flake structure flake-parts (optional structure)
Local quality gates Flake checks
Shared package tweaks Overlays (light introduction)

After this part you should be able to hand a second host or a second user a predictable import graph, activate system + home with one rebuild, and keep project compilers out of the always-on profile.

Prerequisites

From earlier parts of this book you should already be comfortable with:

  • Store paths, closures, and why the store is not private
  • Attrsets, modules, and nixosSystem
  • A working flake host: sudo nixos-rebuild switch --flake .#<host>
  • Generations and rollback
  • Basic SSH/user config on the host

If those are shaky, return to concepts and NixOS host before deepening layout and Home Manager.

Chapter map

Chapter Focus Outcome
Flake repository layout hosts/ · modules/ · homes/ DAG Thin flake.nix; rebuild-equivalent split
Lock file discipline Selective updates, follows, registries Written lock policy; revert skill
Home Manager on NixOS HM as NixOS module, 26.05 pin One rebuild activates system + user
Home files and XDG home.file, xdg.configFile Real configs migrated; secrets out
Home Manager user services systemd.user.* Timers/services that survive reinstall
direnv and project shells devShells + use flake Toolchains load on cd
flake-parts (optional structure) Framework vs hand-rolled helpers House style documented
Flake checks checks + nix flake check Format/shell/host gates
Overlays (light introduction) Small wrappers / overrides Same overlay on host + shell

Mental model — three planes

┌─────────────────────────────────────────────┐
│  flake.nix  (wiring only)                   │
│    inputs → nixosConfigurations / shells    │
└─────────────────┬───────────────────────────┘
                  │
     ┌────────────┼────────────┐
     ▼            ▼            ▼
  hosts/       modules/      homes/
  (machine)    (policy)      (user / HM)
Plane Truth lives in Activated by
Host hosts/<name>/, hardware nixos-rebuild
Policy modules/common, roles, services imported by hosts
User homes/<user>/ via Home Manager same rebuild (module mode)

Rule: host never imported by a common module; user config does not replace system daemons; project compilers do not live forever in home.packages.

Dependency direction (import DAG)

flake.nix
  → hosts/lab
       → modules/common/*
       → modules/roles/*
       → modules/services/*
       → hardware-configuration
       → home-manager.users.<name> → homes/<name>
Allowed Forbidden
Host imports modules Module imports a specific host
Role imports common Common imports role
Service module self-contained Service reaches into hosts/lab
Flake wires HM users Homes import host hardware

Circular graphs fail as infinite recursion or missing attributes. Design the DAG before splitting files.

Suggested repo tree (target shape)

flake.nix
flake.lock
hosts/
  lab/
    default.nix
    hardware-configuration.nix
modules/
  common/
    default.nix
    nix.nix
    users.nix
    ssh.nix
  roles/
    server.nix
    workstation.nix
  services/
homes/
  alice/
    default.nix
    programs.nix
    files.nix
    services.nix
overlays/
  default.nix
lib/
docs/
  layout.md
  lock-policy.md
  flake-style.md

Names are conventions; layering is the invariant.

How to work this part

  1. Layout first — behavior-preserving split of an existing host flake.
  2. Lock policy — before adding HM, sops, or flake-parts inputs casually.
  3. HM module mode — one activation path with the host.
  4. Files and services — migrate real user state deliberately.
  5. direnv — project shells, not profile bloat.
  6. Structure + checks + light overlays — multi-output hygiene.

Prefer small commits: move-only, then feature. Do not mix layout refactors with hardening or new network services.

Cross-cutting conventions (26.05)

Topic Convention in this book
nixpkgs github:NixOS/nixpkgs/nixos-26.05
Home Manager github:nix-community/home-manager/release-26.05 + follows
HM activation NixOS module (home-manager.nixosModules.home-manager)
useGlobalPkgs true so overlays reach HM
Secrets in homes Never plaintext tokens in home.file / text
Project tools flake devShells + direnv, not eternal home.packages

What this part does not cover

Topic Where it lives
sops-nix / agenix Services and security patterns
Fleet deploy, Disko, CI Ops and fleet
Full packaging / overlays mastery Packaging
Day-calendar curriculum Not this book’s model

Skills checklist (end of part)

  • Thin flake wiring; hosts / modules / homes tree
  • Import DAG has no reverse host deps
  • Lock policy written; selective update + revert practiced
  • HM module mode: git + shell for at least one user
  • Two real configs via XDG / home.file or programs.*
  • One user timer or service via HM
  • One project with use flake + direnv
  • House flake style (hand-rolled or flake-parts) documented
  • nix flake check fails on intentional format break
  • One light overlay or wrapper visible on host and shell

How chapters are structured

Each topic chapter typically includes:

  1. Goal and callouts (baseline, pitfalls)
  2. Why this chapter exists — problem framing
  3. Theory sections with tables and full Nix snippets
  4. Worked examples you can paste and adapt
  5. Exercises (8–15) with verify commands
  6. Common gotchas
  7. Checkpoint for self-assessment

Indexes (this file and part openers) orient; topic chapters go deep.

Reading strategies

Mode Approach
First pass Layout → lock → HM → files → services → direnv; then style/checks/overlays
Reference Jump to gotchas + worked example for the tool you need
Audit existing flake Layout + lock + HM boundary chapters first
Laptop vs server Roles chapter patterns; lighter HM on servers

Lab host assumptions

Examples use:

  • Host attr / hostname: lab
  • User: alice (replace with yours)
  • System: x86_64-linux (swap for aarch64-linux as needed)
  • Rebuild: sudo nixos-rebuild switch --flake .#lab

Paths under ~/lab/... are suggestions only—use your real flake repo.

Next part

Services and security patterns builds on this shape: secrets (sops-nix), hardening, firewall, TLS front door, data services, containers, observability. Layout and HM must be boring before those topics get loud.