Guide · Open source
How to use home-manager: setup, configuration and tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
Home Manager is an open-source tool that lets you describe your personal environment, including user-specific packages and configuration files (dotfiles), in Nix configuration files instead of setting them up by hand. It is built on the Nix package manager and the Nixpkgs libraries, and it manages only your user rather than the whole system. This guide explains the three ways to run it, what you need before starting, and the caveats the project itself warns about.
Home Managernix-community/home-manager · ★ 10.5k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm you have the Nix package manager and a NixOS, Linux or nix-darwin system. Read the README warning about difficult errors first.
- 2Clone the repository. Run the clone command from the README to get the project source. Use the manual to find the instructions for your chosen setup.
- 3Pick an installation method. Choose standalone home-manager for any platform, or a NixOS or nix-darwin module if you want user profiles built with the system.
- 4Follow the manual's install section. Work through the standalone, NixOS module or nix-darwin module instructions in the Home Manager manual for your method.
- 5Write a small configuration. Declare a few user packages or dotfiles first, using the options reference to look up settings.
- 6Grow the configuration gradually. Add modules one at a time so that any error is easier to trace to the change that caused it.
What Home Manager needs before you install it
Home Manager is built on the Nix package manager and the Nix libraries found in Nixpkgs, so Nix must be present first. The project targets the nixpkgs-unstable branch and NixOS 26.05, the current stable version, and the README says it may or may not work on other Linux distributions and NixOS versions.
Before you begin, the README asks you to be comfortable with the Nix language and the tools in the Nix ecosystem. Errors can be hard to understand.
- Nix package manager
- NixOS, another Linux system, or nix-darwin on macOS
- Willingness to read and write Nix configuration
Choose how to run Home Manager
Home Manager can be used in three primary ways. The standalone home-manager tool is the only choice on platforms other than NixOS and Darwin. It is also recommended for NixOS or Darwin users who want to manage their home directory independently of the whole system.
On NixOS, Home Manager can be a module inside your system configuration, so user profiles are built together with the system when you run nixos-rebuild. On macOS, the same idea applies through nix-darwin, where profiles are built with darwin-rebuild.
- Standalone home-manager tool: any supported platform, independent of the system
- NixOS module: built along with the system via nixos-rebuild
- nix-darwin module: built along with the system via darwin-rebuild
Install Home Manager
The README describes the installation in general terms and links to the manual for step-by-step instructions for each method: the standalone installation, the NixOS module and the nix-darwin module. Home Manager provides both a channel-based setup and a flake-based one. The manual's Nix Flakes section describes the flake setup.
The only install command in the README is the one that clones the repository. Follow the manual for the rest of the setup that matches your method.
git clone https://github.com/nix-community/home-managerDescribe your environment in Nix configuration
Home Manager lets you declare user-specific, non-global packages and dotfiles. Because the configuration is declarative, you describe the state you want and Home Manager sets up your user environment to match it.
The project provides a searchable list of configuration options in its manual and an options page. A third-party option search is also linked from the README. Use these to find the settings for the modules you need.
- Home Manager manual: systematic overview of the tool
- Configuration options: full list of available options
- 3rd party option search: home-manager-options.extranix.com
Start small and avoid known pitfalls
The README strongly encourages beginners to start with a small, very simple configuration and make it more elaborate gradually. This makes it easier to tell which change caused an error.
Home Manager cannot always detect whether it will overwrite an earlier manual configuration. The README gives the Gnome Terminal module as an example: it writes to your dconf store and cannot tell whether the setting came from a previous Home Manager generation or from manual configuration. Back up settings you care about before applying a new configuration.
- Begin with a minimal configuration and add to it step by step
- Back up manual settings that a module might overwrite
- Expect some error messages to be hard to understand
Stay on a stable release branch
Home Manager is developed against nixpkgs-unstable, which can include changes for packages not yet in stable NixOS. To avoid breaking configurations, the project also releases branches that match NixOS releases. These branches receive fixes but usually not new modules. If you need a module backported, the README suggests opening an issue.
Getting help: the project has an IRC channel, #home-manager on OFTC, and a Matrix room that is bridged to that IRC channel.
What people use it for
- Declaring user-specific packages without installing them system-wide
- Keeping dotfiles reproducible across machines with a Nix configuration
- Building a user profile together with a NixOS system using nixos-rebuild
- Managing a macOS user environment alongside a nix-darwin system with darwin-rebuild
Frequently asked questions
Is Home Manager free to use?
Yes. The project is licensed under the MIT license, as stated in the README and the license file in the repository.
How do I install Home Manager?
The README's only install command clones the repository from GitHub. For the full setup, follow the manual's standalone, NixOS module or nix-darwin module instructions that match your system.
What do I need before installing Home Manager?
You need the Nix package manager and either NixOS, another Linux system, or nix-darwin on macOS. The README also asks you to be comfortable with the Nix language.
Does Home Manager work on Ubuntu or other non-NixOS Linux?
The README says Home Manager targets nixpkgs-unstable and NixOS 26.05, and it may or may not work on other Linux distributions and NixOS versions. The standalone tool is the only option for platforms other than NixOS and Darwin.
Is Home Manager a good choice for beginners?
The README says it is not ideal for beginners. It recommends starting with a small, simple configuration and making it more complex as you learn Nix.
How does Home Manager compare to chezmoi or GNU Stow?
Comparable projects include chezmoi, GNU Stow, yadm and nix-darwin. Home Manager differs because it describes user packages and dotfiles in Nix configuration and is built on Nix and Nixpkgs. This guide does not benchmark them, so compare them against your own needs.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Home Manager suits people who already use Nix or NixOS and want their user packages and dotfiles described in the same declarative system. It is a poor fit for beginners to Nix, for users on non-NixOS Linux who need guaranteed support, or for anyone who wants a point-and-click settings app.
Install options & downloads