NixOS and Home-Manager Essentials

Most Linux systems are configured imperatively. A command installs a package, another command edits a file, a third command enables a service, and the resulting system is whatever combination of actions happened to be run, in whatever order they happened to run. Nobody, including the person who did it, can fully reconstruct that sequence months later. The system's state lives implicitly in a pile of scattered changes rather than in any single readable description. This is the root cause of a familiar problem often called configuration drift, where two machines that were supposedly set up the same way slowly diverge until nobody can explain the differences.

Declarative configuration flips this around. Instead of a sequence of commands, a declarative system is described by a set of files that state the desired end result: which packages should be present, which services should run, which settings should be active. The system reads that description and builds itself to match it. If a file says a particular text editor and a particular shell should be installed, that is what ends up on the machine, regardless of what was installed before. Nothing about the current state depends on memory or habit. The description is the single source of truth, and it can be read from top to bottom like a specification.

Consider a concrete case. On a typical imperative distribution, installing a development environment for a new project usually means running a string of install commands, editing a shell configuration file by hand, and maybe copying some dotfiles from an old machine. Six months later, setting up a second machine the same way means trying to remember that same string of commands, often with a package or two forgotten. On a NixOS and Home-Manager setup, the same environment is described once in files, and applying it on a second machine means copying those files and running a single build command. The description does the remembering.

This matters because reproducibility is not a convenience feature bolted onto NixOS, it is the reason the project exists. A reproducible system is one where the same configuration files produce the same result every time, on any machine, regardless of what was previously installed there. That property comes from how Nix builds and isolates packages, a topic covered in depth when the chapter on the Nix ecosystem explains how the package manager, the distribution, and the user environment tool relate to one another. For now, the important point is that reproducibility eliminates a whole category of debugging where the question is simply what is different about this machine?

Declarative configuration also makes a system easier to reason about because the description can be treated like ordinary source code. It can be stored in a version control system, reviewed line by line, compared against an earlier version, and rolled back if something in it turns out to be wrong. A dotfile edited by hand leaves no history unless someone remembers to keep one manually. A dotfile generated from a declarative configuration file that lives in a repository carries its own history automatically, because every change to it is a change to a tracked text file. Chapters on managing dotfiles and on version-controlling a configuration build directly on this idea.

None of this means imperative tools disappear entirely, and it does not mean every single action on a NixOS machine must go through a configuration file. It means the core, structural parts of a system, the packages, the services, the settings that define how the machine behaves, are captured declaratively rather than left to accumulate as an unrecorded history of commands. That shift is the single idea underneath everything else in this book, and it is worth sitting with before moving into any of the mechanics.

The chapters that follow move from foundational concepts toward a fully built, production-ready personal system, in roughly the order a newcomer would need them. Early chapters establish vocabulary and mental models. Middle chapters build practical skill with the tools themselves. Later chapters combine those skills into something a reader can actually run day to day. The path is designed so that each chapter's ideas are used again in the chapters that follow, rather than sitting isolated.

The first stretch of the book explains the pieces of the Nix ecosystem and how they relate. This includes the difference between the Nix package manager, the NixOS distribution built on top of it, and Home-Manager as a separate but complementary tool for user-level configuration. It also introduces the distinction between system-level and user-level configuration, a boundary that recurs constantly: some settings belong to the whole machine and are shared across every user, while others belong to a single person's account and should not depend on which machine that account happens to be logged into.

From there, the book moves into hands-on installation. A dedicated chapter walks through getting NixOS running on a machine for the first time, explaining configuration.nix and hardware-configuration.nix as the two files that describe a system's desired state and its hardware specifics, and showing how nixos-rebuild takes that description and turns it into a running system. This is the first point in the book where the declarative idea from the previous subchapter becomes something typed into a terminal and actually observed.

Understanding those configuration files requires understanding the language they are written in, so a full chapter is dedicated to the Nix Expression Language: its syntax, its data types, its functions, and the attribute set structure that appears everywhere in Nix code. A companion chapter steps back to explain the functional programming ideas that shape why the language works the way it does, covering pure functions, lazy evaluation, and immutability. These two chapters are meant to be read close together, since the language chapter shows the syntax and the functional programming chapter explains why that syntax behaves the way it does.

With the language covered, the book turns to Home-Manager specifically, showing how it is installed, how home.nix is structured, and how it replaces manual dotfile editing with declarative statements about which programs should be configured and how. A reader who has spent years hand-editing shell configuration files or copying them between machines will find this chapter directly addresses that recurring frustration.

The second half of the book covers flakes, the modern mechanism for pinning exact versions of everything a configuration depends on through flake.nix and the generated flake.lock file, which is what makes a configuration reproducible not just on one machine today but on any machine at any point in the future. A chapter on advanced customization then shows how to manage system packages, development environments, multiple user profiles, and custom NixOS modules, giving the tools needed to adapt everything covered so far to a specific real setup rather than a generic example.

Two final chapters close out the practical arc. One explains how atomic upgrades, generations, and rollback work mechanically, framing them as a safety net that makes experimentation low-risk rather than something to be feared. The other pulls every earlier idea together into a single guided process for planning, modularizing, version-controlling, and maintaining a personal system that can keep growing after the book ends. The following table gives a quick view of that same path.

Some topics are deliberately left out or only touched briefly, because this book focuses on a single machine used by a single person rather than on managing fleets of servers or contributing packages upstream to Nixpkgs. The goal throughout is depth on the path from never used NixOS to runs a real, working, version-controlled NixOS and Home-Manager setup day to day, not breadth across every possible use of the Nix ecosystem.

It is fair to expect some friction along the way. The functional style of the Nix Expression Language, the strictness of pure functions, and the unfamiliar shape of attribute sets can feel foreign at first, especially coming from more conventional configuration formats. That friction is normal and temporary, and the chapters on functional programming concepts are structured specifically to work through it with examples rather than abstract description alone.

By the final chapter, the aim is not just familiarity with terminology but the ability to open a personal configuration repository, understand every file in it, make a change with confidence, and know exactly how to undo that change if it turns out to be wrong. That combination of confidence and safety is what the rest of this book is building toward.

This book is written to be read in order, at least for the first pass. Later chapters assume the vocabulary and tools introduced earlier, and the Nix Expression Language chapter in particular is meant to be firmly understood before moving into Home-Manager and flakes, since both of those depend heavily on reading and writing that language comfortably. Skipping ahead is possible, but expect to backtrack occasionally when an unfamiliar term shows up.

A working NixOS installation, or at minimum access to a virtual machine or spare machine where NixOS can be installed, will make the hands-on chapters far more useful than reading alone. Concepts like declarative configuration and atomic upgrades are easy to nod along with in the abstract but become genuinely clear only once a real nixos-rebuild has been run and a real rollback has been triggered. Wherever practical, follow along on an actual machine rather than treating the examples as purely illustrative.

The following checklist offers a simple way to prepare before diving into the installation chapter, so that the early hands-on material goes smoothly rather than stalling on setup issues unrelated to Nix itself.

Each chapter builds toward practical skill rather than pure theory, so expect commands to type, files to edit, and small experiments to run rather than only descriptions to read. When a chapter introduces a new file, such as configuration.nix or home.nix, the most effective approach is to have that file open in an editor while reading, making the same edits described in the text rather than only reading about them. Passive reading works far less well with a tool this hands-on than active practice does.

Mistakes along the way are expected and, on NixOS, unusually safe. One of the qualities that sets this system apart from most other Linux distributions is that a broken configuration rarely means a broken machine, because the previous working generation remains available and a rollback can restore it in moments. This safety net is explained in detail in the chapter on atomic upgrades and rollbacks, but it is worth internalizing early: experimentation here carries far less risk than it does on a traditional distribution, so treat mistakes as part of the learning process rather than something to avoid at all costs.

For readers who already have some exposure to Nix, certain early sections, particularly the ecosystem overview and the basic installation walkthrough, may move slowly. Even so, skimming rather than skipping those sections is worth doing, since later chapters use the exact terminology established there and assume a shared vocabulary. A reader who skips ahead and later encounters an unfamiliar term is better served by returning to the earlier chapter than by guessing at a definition.

The glossary near the end of the book collects the recurring terms used throughout, including declarative configuration, generation, reproducibility, and others introduced along the way, and can be used as a quick reference whenever a term feels unclear mid-chapter rather than fully forgotten. The further reading section similarly points toward official documentation and community resources for topics that go beyond what a single beginner-focused book can cover in full depth.

Above all, treat this as a book meant to be used alongside a running system rather than read at a distance from one. The ideas of declarative configuration, reproducibility, and safe experimentation are straightforward to state in a paragraph but become genuinely convincing only once experienced directly, the first time a configuration change breaks something and a rollback quietly fixes it in seconds. That moment, more than any explanation in this introduction, is where the appeal of this approach to Linux truly becomes clear.