Home Manager — Manage User Environments with Nix

Introduction

Home Manager uses the Nix package manager to declaratively configure user-level programs, dotfiles, and services. You describe your desired environment in a single configuration file, and Home Manager builds and activates it atomically with full rollback support.

What Home Manager Does

• Declaratively manages dotfiles, shell configuration, and program settings via Nix expressions
• Installs user-scoped packages without requiring root access or modifying system state
• Provides atomic activation with instant rollback to any previous generation
• Manages systemd user services on Linux and launchd agents on macOS
• Integrates with NixOS modules or runs standalone on any Linux or macOS system

Architecture Overview

Home Manager evaluates a user's home.nix configuration to produce a Nix derivation that contains all managed files, packages, and service definitions. On activation, it creates a new generation in the Nix store, symlinks managed dotfiles into the home directory, and starts or restarts any declared services. Previous generations remain in the store for rollback.

Self-Hosting & Configuration

• Requires Nix package manager installed on the host system
• Configuration lives in ~/.config/home-manager/home.nix by default
• Use home-manager switch to build and activate the current configuration
• Roll back with home-manager generations and home-manager activate on a previous generation
• Can be used as a NixOS module or a standalone Flake input for multi-machine setups

Key Features

• Over 1,500 module options covering shells (bash, zsh, fish), editors (Neovim, Emacs), and desktop environments
• Full Flake support for pinning dependencies and sharing configurations across machines
• DAG-based activation ordering ensures correct startup sequencing for services
• Supports conditional configuration based on hostname, platform, or custom predicates
• Community-maintained modules for Git, tmux, SSH, GPG, Firefox, and many more programs

Comparison with Similar Tools

• GNU Stow — Symlink-based dotfile manager with no dependency management; Home Manager handles both packages and dotfiles
• chezmoi — Go-based dotfile manager with templating; Home Manager adds declarative package and service management via Nix
• Ansible (user scope) — General-purpose automation tool; Home Manager is Nix-native with atomic rollback and reproducible builds
• yadm — Git-based dotfile manager with encryption; Home Manager provides a higher-level abstraction with typed module options
• Nix-Darwin — macOS system-level Nix configuration; Home Manager focuses on user-level config and composes with Nix-Darwin

FAQ

Q: Do I need NixOS to use Home Manager? A: No. Home Manager runs standalone on any Linux distribution or macOS with the Nix package manager installed.

Q: Can I manage the same configuration across multiple machines? A: Yes. Using Nix Flakes, you can define per-host configurations in a single repository with shared modules and machine-specific overrides.

Q: How do I roll back a bad configuration change? A: Run home-manager generations to list previous generations, then activate a previous one. The old generation remains intact in the Nix store.

Q: Does Home Manager conflict with system-level package managers? A: Home Manager installs packages into the Nix store and symlinks them into the user profile. It does not modify system package databases and coexists with apt, brew, or pacman.

Sources

• https://github.com/nix-community/home-manager
• https://nix-community.github.io/home-manager/