DOCSEARCHbyAlgolia
Submit Docs

Home Manager Documentation

repository·master·Indexed 27 days ago

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

A declarative system for managing user-specific packages and dotfiles using the Nix package manager and Nixpkgs. Supports standalone installation, NixOS modules, and nix-darwin modules, with both channel-based and flake-based setups. Includes guides on configuration via home.nix, managing environment generations, and resolving package collisions.

Tokens
18.7K
Snippets
49
Records
108
Agent score
93%

What's inside Home Manager

  1. Overview of Home Manager

    master

    Home Manager is a Nix-powered tool designed for the reproducible management of user home directories. It allows you to manage programs, configuration files, environment variables, and arbitrary files through Nix code.

    Key benefits include:

    • Reproducibility: Ensures home directories are identical across builds and different hosts.
    • Program & Config Management: Unlike traditional dotfile repositories, it manages both the software (executables) and their specific configurations.
    • Nix Integration: Leverages Nixpkgs for access to extensive software repositories and supports building programs from source via Nix.
    • Composability: Allows different configuration files and build instructions to share a single source of truth.

  2. Release Schedule and Branching Strategy

    master

    Home Manager releases stable versions twice a year, synchronized with NixOS/nixpkgs:

    • May: YY.05 version
    • November: YY.11 version

    Stable branches (e.g., release-25.11) are cut from the master branch. While branches can be created before a NixOS release reaches "beta", documentation and links on the master branch should only be updated once the stable version is officially out of beta.

  3. Choose a Home Manager installation method

    master

    Home Manager can be installed in three primary ways depending on your operating system and management preferences:

    1. Standalone tool: Use this for platforms other than NixOS and Darwin (e.g., Ubuntu, Fedora, macOS without nix-darwin). It is also recommended for NixOS or Darwin users who want to manage their home directory independently of the system configuration.
    2. NixOS module: Integrate Home Manager into your NixOS system configuration. This allows user profiles to be built alongside the system when running nixos-rebuild.
    3. nix-darwin module: Integrate Home Manager into a nix-darwin system configuration. This allows user profiles to be built alongside the system when running darwin-rebuild.

    Note: The following installation instructions assume the use of Nix channels. If you prefer to use Nix Flakes, refer to the Nix Flakes documentation.

  4. Understand Home Manager activation scripts

    master

    Home Manager uses an activate Bash script generated during the configuration build to apply changes to the user's environment. This script is located in the root of the build output.

    The script is composed of initialization code and multiple activation script blocks defined via the home.activation option. These blocks can have dependencies, and the generated script serializes them to ensure dependencies are satisfied. Note that dependency cycles will cause build failures.

  5. Change a module's package using Nixpkgs overlays

    master

    If a Home Manager module does not provide a package option, you can change the package it uses by applying a Nixpkgs overlay. This replaces the package in the package set used by Home Manager.

    Standalone Home Manager

    In a standalone configuration, add the overlay to nixpkgs.overlays:

    { pkgs, config, ... }:

let
  pkgsUnstable = import <nixpkgs-unstable> {};
in
{
  programs.skim.enable = true;

  nixpkgs.overlays = [
    (_final: _prev: {
      skim = pkgsUnstable.skim;
    })
  ];
}

    Home Manager as a NixOS or nix-darwin module

    If home-manager.useGlobalPkgs = false (default): You can use the same overlay method within your Home Manager configuration as shown in the standalone example above. If using Flakes, ensure pkgsUnstable is passed to the module.

    If home-manager.useGlobalPkgs = true is enabled: Home Manager uses the system package set, and nixpkgs.* options inside Home Manager are disabled. You must apply the overlay to the system configuration instead:

    { pkgsUnstable, ... }:

{
  nixpkgs.overlays = [
    (_final: _prev: {
      skim = pkgsUnstable.skim;
    })
  ];
}

    In Flake-based NixOS or nix-darwin configurations, pass pkgsUnstable to nixosSystem or darwinSystem using specialArgs.

  6. Upgrade Home Manager using Nix Flakes

    master

    When using Nix flakes, you must update both your nixpkgs and home-manager inputs to matching release branches.

    For stable releases (e.g., 25.11), use the release-<version> branch. For unstable configurations, use the master branch.

    After updating the inputs in your flake file, update the lock file and rebuild using the command corresponding to your installation method.

  10. Run a minimal modular service

    master

    Home Manager supports nixpkgs modular services via the home.services namespace. This allows you to run services as user-level systemd units using the same modules used in NixOS. A minimal service configuration requires defining process.argv to specify the command to run.

    { pkgs, ... }: {
  home.services.mpd = {
    process.argv = [ "${pkgs.mpd}/bin/mpd" "--no-daemon" ];
  };
}

  11. Use Home Manager as a NixOS module with Flakes

    master

    To integrate Home Manager directly into your NixOS configuration using Flakes, include home-manager.nixosModules.home-manager in your nixosSystem modules list. This allows you to manage user configurations as part of the system rebuild process.

    Key configuration options for the NixOS module:

    • home-manager.useGlobalPkgs = true;: Uses the system's package set instead of a separate one for Home Manager.
    • home-manager.useUserPackages = true;: Uses the system's package set for user packages.
    • home-manager.extraSpecialArgs: An attribute set used to pass arguments (like flake inputs) from the flake to your home.nix and other Home Manager modules.
    • home-manager.users.<username>: Defines the Home Manager configuration file for a specific user.
    {
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    home-manager.url = "github:nix-community/home-manager";
  };

  outputs = inputs@{ nixpkgs, home-manager, ... }: {
    nixosConfigurations = {
      hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          home-manager.nixosModules.home-manager
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.extraSpecialArgs = { inherit inputs; };
            home-manager.users.jdoe = ./home.nix;
          }
        ];
      };
    };
  };
}

  12. Change the package used by a Home Manager module via the `package` option

    master

    If a Home Manager module provides a package option (e.g., programs.beets.package), you can override the default package by assigning a different one to that option. This is the recommended method for changing a package version or applying overrides.

    To use a package with specific overrides:

    programs.beets.package = pkgs.beets.override { pluginOverrides = { beatport.enable = false; }; };

    To use a package from a different Nixpkgs channel (like unstable) in a standard configuration:

    { pkgs, config, ... }:

let
  pkgsUnstable = import <nixpkgs-unstable> {};
in
{
  programs.beets.package = pkgsUnstable.beets;
}

    To use a package from a different channel in a Flake-based configuration, pass the unstable package set as an extra module argument and use it directly:

    { pkgsUnstable, ... }:

{
  programs.beets.package = pkgsUnstable.beets;
}