home-manager

Build the configuration defined in ~/.config/nixpkgs/home.nix without applying it

$ home-manager build

$ home-manager switch

$ home-manager rollback

$ home-manager generations

$ home-manager [command] --flake [path/to/flake]

home-manager [global-options] command [command-options] [arguments]

Common commands:
    home-manager switch [--flake uri]
    home-manager generations [subcommand]
    home-manager update

--help
    Displays help information for the command or subcommand.

--version
    Prints the home-manager version number.

--flake uri
    Specifies a Nix flake URI (e.g., 'path:./#home-manager') to use for the configuration, enabling a more modern and reproducible setup.

--impure
    Allows the build to access external files or the network, making it "impure" and potentially less reproducible.

--dry-run
    Performs a trial run without making any actual changes to the system, showing what would happen.

--show-trace
    Shows a stack trace on Nix evaluation errors, aiding in debugging configuration issues.

--verbose
    Increases the verbosity of the output, providing more detailed information about the operation.

-f file, --file file
    Specifies the home-manager configuration file to use. Default is typically 'home.nix' or specified via flake inputs.

--no-warn-extra-config
    Disables warnings about extra configuration options found in the system-wide Nix configuration.

home-manager is a powerful tool built on top of the Nix package manager, designed to declaratively manage a user's home directory configuration and installed packages. Unlike traditional methods of managing dotfiles and user-specific software (e.g., symlinks, manual installations), home-manager provides a reproducible and atomic way to define your entire user environment using Nix expressions. This means you can specify your shell configuration (bash, zsh, fish), text editor setups (Neovim, Emacs), desktop applications, user-level services, and even environment variables in a single, version-controlled configuration file.

It leverages Nix's atomic upgrades and rollbacks, allowing you to switch between configurations safely or revert to a previous working state if issues arise. home-manager can be used standalone on any Linux distribution (requiring only Nix to be installed) or integrated seamlessly with NixOS, complementing the system-wide configuration. Its primary goal is to make managing your personal computing environment reproducible, portable, and easy to share across multiple machines or with other users. By defining your home configuration declaratively, you gain confidence that your setup will be consistent regardless of the underlying system, simplifying setup for new machines and ensuring consistency over time.

The learning curve for Nix and its functional programming paradigm can be steep for new users, requiring time to understand declarative configurations and the Nix language.
Initial builds and significant configuration changes can be resource-intensive due to Nix's atomic and reproducible build processes.
Debugging complex home-manager configurations sometimes requires a deep understanding of Nix evaluation and error traces.
While powerful, its dependency on the Nix ecosystem means users must manage Nix channels or flake inputs, ensuring they are kept up-to-date for consistent and secure environments.

home-manager embodies the principle of declarative configuration, where the desired state of the user's environment is specified in a Nix expression, rather than a sequence of imperative commands. This approach ensures reproducibility and consistency across different machines, as the configuration describes "what" the environment should be, not "how" to achieve it.

Leveraging the capabilities of the Nix package manager, home-manager performs atomic upgrades and rollbacks. Each activation of a new configuration creates a new "generation" in the Nix store. If a new configuration causes issues, users can instantly revert to a previous, known-working generation, significantly reducing the risk of broken environments.

home-manager emerged from the Nix and NixOS community as a solution to the challenge of managing user-level configurations in a reproducible and declarative manner, similar to how NixOS manages system-wide configurations. Initially, users would often try to manage dotfiles manually or with simpler tools, which lacked the atomic updates and rollbacks provided by Nix. home-manager filled this gap by leveraging Nix's powerful functional package management capabilities to build and manage user environments from declarative specifications. Its development has been driven by the Nix community, evolving alongside Nix itself, with significant advancements particularly in integrating with the modern Nix "flakes" system, which further enhances reproducibility and ease of sharing configurations. It has become an essential tool for many NixOS users and those on other Linux distributions seeking a robust, portable, and version-controlled way to manage their personal computing setup.

nix(1), nix-env(1), nix-store(7), nixos-rebuild(8), git(1)