home-manager
Manage user configuration declaratively with Nix
TLDR
Build the configuration defined in ~/.config/nixpkgs/home.nix without applying it
Build and apply (switch to) the new configuration
Roll back to a previous configuration generation
List all existing configuration generations
When using flakes, run any operation that requires nix to run (build, switch, news) by passing the path to the flake
SYNOPSIS
home-manager [OPTION …] COMMAND [ARGS …]
PARAMETERS
--help
Display help and exit
--version
Display version information
--flake <PATH>
Use Nix flakes for evaluation from specified path
--impure
Allow impure derivations (e.g., accessing /etc)
--print-build-logs
Print full build logs on failure
--show-trace
Show a trace of evaluation errors
--arg <name> <value>
Pass Nix expression as argument
--argstr <name> <string>
Pass string as argument
--override-input <input> <path>
Override flake input
-f <FILE>
Evaluate FILE as configuration (legacy)
DESCRIPTION
Home Manager is a tool for declaratively managing a user's home directory using the Nix package manager. It allows users to define their entire user environment—including packages, dotfiles, programs, and services—in a single Nix configuration file, typically home.nix. Upon running home-manager switch, it builds and activates the specified configuration, creating a generational profile similar to NixOS system generations.
This enables reproducible, versioned user setups across machines, with rollback capabilities. It's particularly useful on NixOS for per-user customization without root privileges, or on non-NixOS Linux/macOS systems via Nix. Configurations are purely functional, ensuring no side effects outside the profile. Home Manager integrates seamlessly with Nix flakes for modern, locked dependencies.
Key benefits include atomic upgrades, easy sharing of configs (e.g., via Git), and managing XDG portals, fonts, and desktop environments declaratively.
CAVEATS
Requires Nix installed; flakes need experimental features enabled. Non-NixOS users must bootstrap carefully. Configurations may conflict with manual dotfiles. Large configs can be slow to build.
COMMON COMMANDS
switch: Build/activate config.
build: Build without activating.
news: Show configuration news.
expire-generations: Clean old generations.
INSTALLATION
On NixOS: environment.systemPackages = [ pkgs.home-manager ];
Standalone: nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager then nix-channel --update.
HISTORY
Originated in 2017 by Nicolas “rycee” Williams as an alternative to nix-home, evolving into official Home Manager project under NixOS org. Initial 19.03 release integrated with Nixpkgs; flakes support added in 21.11. Now widely used for dotfile management, with active community modules.
SEE ALSO
nix(1), nix-channel(1), nixos-rebuild(8), nix flake(1)
