# Home Manager: your home directory as a Nix program, and the warning the README leads with > A declarative layer for user packages, dotfiles and services on top of nixpkgs, with a documentation section titled words of warning and 983 open issues. **nix-community/home-manager** — Manage a user environment using Nix [maintainer=@khaneliman, @rycee] - Repository: https://github.com/nix-community/home-manager - Website: https://nix-community.github.io/home-manager/ - Stars: 10,458 · Forks: 2,500 - Language: Nix - License: MIT - Published: 2026-10-07 · Updated: 2026-10-07 · Language: en - Canonical page: https://hysenlabs.com/projects/nix-community-home-manager ## A user-environment layer, not a system configuration Home Manager provides a basic system for managing a user environment using the Nix package manager together with the Nix libraries found in nixpkgs. The specific claim is declarative configuration of user-specific, non-global packages and dotfiles. That boundary is the concept worth holding on to: this is the layer below your system configuration and above nothing, and it is deliberately scoped to what belongs to a user rather than to root. So programs installed through Home Manager, editor configuration, shell environment, fonts, git settings, X resources and user services all live in one module system that is evaluated by Nix. Because it is Nix rather than a bespoke configuration format, every tool available in nixpkgs is available to you, and the same version pinning logic that makes a NixOS system reproducible applies to the applications in your home directory. The dependency is real and worth stating plainly: this project assumes nixpkgs as its library, so you are committing to the Nix ecosystem's abstraction, including its learning curve, as a condition of using it. The tree shows how the project is organised around that. `modules/` holds the module definitions that make up the bulk of the work, `home-manager/` is the standalone entry point, `nixos/` and `nix-darwin/` are the module wrappers for each platform, `lib/` holds shared helpers, `templates/` provides starting configurations, and `tests/` holds the module test suite. There is also `docs/` for the manual sources, `ci/` for continuous integration, and a `Justfile` beside a `Makefile` for task running. ## Three ways to install, and they are not equivalent The README describes three primary installation methods, and the differences between them matter more than the enumeration suggests. The first is the standalone `home-manager` tool. For platforms other than NixOS and Darwin, the README states this is the only available choice. It is also recommended for people on NixOS or Darwin who want to manage their home directory independently of the system as a whole, which is the interesting case: it decouples the user environment from the operating system configuration, so you can rebuild the system without touching your dotfiles and rebuild your dotfiles without rebuilding the system. The second is as a module within a NixOS system configuration. Here the user profiles are built together with the system when running `nixos-rebuild`, so your applications are declared in one place and change atomically with the system. The third is the nix-darwin equivalent, built together with the system when running `darwin-rebuild`, for macOS. The practical difference is coupling. The NixOS module is less flexible but more coherent, since there is exactly one configuration to rebuild. Standalone gives you independence at the cost of having two rebuild commands to remember and the possibility that they disagree about package versions. Choosing NixOS-and-Darwin standalone is a reasonable position for anyone whose home directory outlives their operating system installation, and the README recommends it for exactly that reason. Both channel-based and flake-based setup are provided, and the README points at the manual's flake section for the latter. New installations should use flakes, since channels are the older mechanism and the ecosystem documentation has moved on. ## The words of warning section is the most useful documentation Before the installation instructions, the README tells you to read a section called words of warning, and that section is worth more than most projects' getting-started guides. It says that it is quite possible to get difficult to understand errors when working with Home Manager, and that you should therefore be comfortable using the Nix language and the various tools in the Nix ecosystem. If you are not very familiar with Nix but still want to use Home Manager, you are strongly encouraged to start with a small and very simple configuration and gradually make it more elaborate as you learn. The specific hazard named is worth internalising. In some cases Home Manager cannot detect whether it will overwrite a previous manual configuration. The example given is the Gnome Terminal module, which writes to your dconf store and cannot tell whether a configuration that is about to be overwritten came from a previous Home Manager generation or from manual configuration. So the failure mode is silent and irreversible in a particular way: you change something outside the tool, run the tool, and your change is gone with no record of it. That is the real cost of declarative configuration, and this project names it instead of hoping you find out later. Anything Home Manager manages is owned by it, and the boundary of that ownership is exactly where data gets lost. The README also states the support target plainly, and it is narrower than you might expect: Home Manager targets nixpkgs-unstable and NixOS version 26.05, the current stable version, and it may or may not work on other Linux distributions and NixOS versions. So there is a specific supported combination, and on other distributions you are outside it. ## Release branches track NixOS releases, which changes the upgrade story The release model is explained in a way that directly affects how you should pin things. Home Manager is developed against the nixpkgs-unstable branch, which often causes it to contain tweaks for changes and packages not yet released in stable NixOS. To avoid breaking user configurations, releases go out in branches corresponding to NixOS releases, for example `release-26.05`. Those branches receive fixes but usually not new modules. That last clause is the important one. Following a release branch gives you a configuration that keeps working, at the cost of not getting new modules. Tracking the development version gives you new modules immediately, at the cost of breaking when nixpkgs changes underneath you. The README says that if you need a module backported you can open an issue, which is both an offer and an admission that it will not happen automatically. So the upgrade decision is a genuine trade rather than a matter of pressing a button. For a machine you rebuild frequently and can fix quickly, tracking development is reasonable. For a laptop you want to forget about, a release branch matched to your NixOS version is the sane choice, and the branch name is the only thing you need to get right. The release model also explains the size of the open issue count. With 983 open issues and 2,479 forks, this is a project with a very large user base, and a substantial fraction of those issues will be requests to backport a module to a release branch, which is a category the maintainers handle on their own schedule. ## Testing infrastructure and the tools a contributor actually uses The Makefile is small and reveals the shape of the project's own development. It pins the nixpkgs revision to `nixpkgs-unstable` and builds a NIX_PATH from it, and it refuses to run tests without an explicit target name, which prevents a bare `make test` from silently running the entire suite. Each test is then run through `nix-shell` against the tests directory: ```bash NIXPKGS_REV := nixpkgs-unstable NIX_PATH := nixpkgs=https://github.com/NixOS/nixpkgs/archive/${NIXPKGS_REV}.tar.gz ``` There is a separate `test-install` target that runs the install target with a fresh temporary HOME, which is the kind of check that catches installation bugs you would otherwise find by breaking your own machine. And the `format` target has been retired in favour of running the formatter through a dev shell via Just, with a comment recording the change date as 2026-03-01. The rest of the tree shows a mature configuration. `default.nix` and `flake.nix` both exist, so the project supports both entry points for itself as well as for its users. There is a `flake-module.nix` for consuming Home Manager as a flake input, `overlay.nix` and `all-maintainers.nix` for packaging integration, and `treefmt.toml` plus `statix.toml` for formatting and Nix static analysis. `nixbot.toml` configures automatic merge automation, which is a reasonable choice for a project with this volume of routine pull requests. The translation story is modest but present: basic internationalization through gettext, with translations hosted on Weblate. And support is IRC on `#home-manager` at OFTC with a Matrix room bridged to that channel, so the two are the same conversation rather than a fallback pair. The MIT licence is stated plainly, with no exceptions or additional terms, which is the simplest licensing situation in this batch. ## Conclusion Home Manager is the right tool if you already live in Nix and want your user environment to be as reproducible as your system, and the wrong tool if you are approaching it as a dotfiles tidy-up. The README is unusually honest that it can be difficult to understand, that you should already be comfortable with the Nix language, and that some modules cannot tell a previous generation from a manual configuration and will overwrite it. Both channel-based and flake-based setup are supported, and the branch scheme tracks NixOS releases, so pinning a release branch is the difference between a module update arriving and your configuration breaking. Start standalone on a single-user machine, and read the warnings before the modules rather than after. ## FAQ ### How do I install Home Manager? There are three routes. Use the standalone home-manager tool, which is the only option on platforms other than NixOS and Darwin. Or add it as a module in a NixOS configuration, where profiles build together with the system via nixos-rebuild. Or add it as a module in a nix-darwin configuration for macOS, using darwin-rebuild. Both channel-based and flake-based setups are supported. ### What does home manager mean here? It refers to managing the non-global, per-user environment: the packages you install, your dotfiles and your user services. Home Manager is the layer that sits below a system configuration, so it can run standalone, or as a module inside a NixOS or nix-darwin configuration where user profiles are built with the system. ### Is Home Manager safe to try if I am new to Nix? The README recommends against it as a starting point. It states that you should be comfortable with the Nix language first, and that people who are not should begin with a small and simple configuration and add complexity gradually. It also warns that some modules cannot tell a previous Home Manager generation from a manual configuration and will overwrite it, so a change made outside the tool can be lost without a record. ### Which branch of Home Manager should I use? Home Manager is developed against nixpkgs-unstable but released in branches matching NixOS releases, such as release-26.05, to avoid breaking configurations. Release branches receive fixes but usually not new modules. Pin a release branch for stability, and open an issue if you need a specific module backported. ## Sources - [Issues](https://github.com/nix-community/home-manager/issues) - [License: MIT](https://github.com/nix-community/home-manager/blob/master/LICENSE) - [nix-community/home-manager on GitHub](https://github.com/nix-community/home-manager) - [Project website](https://nix-community.github.io/home-manager/) - [README](https://github.com/nix-community/home-manager/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nix-community-home-manager