If instead of using channels you want to run Home Manager from a Git checkout of the repository then you can use the home-manager.path option to specify the absolute path to the repository.

Once installed you can see Using Home Manager for a more detailed description of Home Manager and how to use it.

Home Manager provides a NixOS module that allows you to prepare user environments directly from the system configuration file, which often is more convenient than using the home-manager tool. It also opens up additional possibilities, for example, to automatically configure user environments in NixOS declarative containers or on systems deployed through NixOps.

To make the NixOS module available for use you must import it into your system configuration. This is most conveniently done by adding a Home Manager channel to the root user. For example, if you are following Nixpkgs master or an unstable channel, you can run

$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
$ sudo nix-channel --update

and if you follow a Nixpkgs version 23.11 channel, you can run

$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.11.tar.gz home-manager
$ sudo nix-channel --update

It is then possible to add

imports = [ <home-manager/nixos> ];

to your system configuration.nix file, which will introduce a new NixOS option called home-manager.users whose type is an attribute set that maps user names to Home Manager configurations.

For example, a NixOS configuration may include the lines

users.users.eve.isNormalUser = true;
home-manager.users.eve = { pkgs, ... }: {
  home.packages = [ pkgs.atool pkgs.httpie ];
  programs.bash.enable = true;

  # The state version is required and should stay at the version you
  # originally installed.
  home.stateVersion = "23.11";
};

and after a sudo nixos-rebuild switch the user eve’s environment should include a basic Bash configuration and the packages atool and httpie.

$ systemctl status "home-manager-$USER.service"

If you do not plan on having Home Manager manage your shell configuration then you must add either

. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"

or

. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"

to your shell configuration, depending on whether home-manager.useUserPackages is enabled. This file can be sourced directly by POSIX.2-like shells such as Bash or Z shell. Fish users can use utilities such as foreign-env or babelfish.

home-manager.useUserPackages = true;

home-manager.useGlobalPkgs = true;

{ lib, pkgs, osConfig, ... }:

Once installed you can see Using Home Manager for a more detailed description of Home Manager and how to use it.

Home Manager provides a module that allows you to prepare user environments directly from the nix-darwin configuration file, which often is more convenient than using the home-manager tool.

To make the NixOS module available for use you must import it into your system configuration. This is most conveniently done by adding a Home Manager channel. For example, if you are following Nixpkgs master or an unstable channel, you can run

$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
$ nix-channel --update

and if you follow a Nixpkgs version 23.11 channel, you can run

$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.11.tar.gz home-manager
$ nix-channel --update

It is then possible to add

imports = [ <home-manager/nix-darwin> ];

to your nix-darwin configuration.nix file, which will introduce a new NixOS option called home-manager whose type is an attribute set that maps user names to Home Manager configurations.

For example, a nix-darwin configuration may include the lines

users.users.eve = {
  name = "eve";
  home = "/Users/eve";
};
home-manager.users.eve = { pkgs, ... }: {
  home.packages = [ pkgs.atool pkgs.httpie ];
  programs.bash.enable = true;

  # The state version is required and should stay at the version you
  # originally installed.
  home.stateVersion = "23.11";
};

and after a darwin-rebuild switch the user eve’s environment should include a basic Bash configuration and the packages atool and httpie.

If you do not plan on having Home Manager manage your shell configuration then you must add either

. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"

or

. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"

to your shell configuration, depending on whether home-manager.useUserPackages is enabled. This file can be sourced directly by POSIX.2-like shells such as Bash or Z shell. Fish users can use utilities such as foreign-env or babelfish.

home-manager.useUserPackages = true;

home-manager.useGlobalPkgs = true;

{ lib, pkgs, osConfig, ... }:

Once installed you can see Using Home Manager for a more detailed description of Home Manager and how to use it.

A fresh install of Home Manager will generate a minimal ~/.config/home-manager/home.nix file containing something like

{ config, pkgs, ... }:

{
  # Home Manager needs a bit of information about you and the
  # paths it should manage.
  home.username = "jdoe";
  home.homeDirectory = "/home/jdoe";

  # This value determines the Home Manager release that your
  # configuration is compatible with. This helps avoid breakage
  # when a new Home Manager release introduces backwards
  # incompatible changes.
  #
  # You can update Home Manager without changing this value. See
  # the Home Manager release notes for a list of state version
  # changes in each release.
  home.stateVersion = "23.11";

  # Let Home Manager install and manage itself.
  programs.home-manager.enable = true;
}

You can use this as a base for your further configurations.

As an example, let us expand the initial configuration file to also install the htop and fortune packages, install Emacs with a few extra packages available, and enable the user gpg-agent service.

To satisfy the above setup we should elaborate the home.nix file as follows:

{ config, pkgs, ... }:

{
  # Home Manager needs a bit of information about you and the
  # paths it should manage.
  home.username = "jdoe";
  home.homeDirectory = "/home/jdoe";

  # Packages that should be installed to the user profile.
  home.packages = [
    pkgs.htop
    pkgs.fortune
  ];

  # This value determines the Home Manager release that your
  # configuration is compatible with. This helps avoid breakage
  # when a new Home Manager release introduces backwards
  # incompatible changes.
  #
  # You can update Home Manager without changing this value. See
  # the Home Manager release notes for a list of state version
  # changes in each release.
  home.stateVersion = "23.11";

  # Let Home Manager install and manage itself.
  programs.home-manager.enable = true;

  programs.emacs = {
    enable = true;
    extraPackages = epkgs: [
      epkgs.nix-mode
      epkgs.magit
    ];
  };

  services.gpg-agent = {
    enable = true;
    defaultCacheTtl = 1800;
    enableSshSupport = true;
  };
}

To activate this configuration you can run

home-manager switch

or if you are not feeling so lucky,

home-manager build

which will create a result link to a directory containing an activation script and the generated home directory files.

While the home-manager tool does not explicitly support rollbacks at the moment it is relatively easy to perform one manually. The steps to do so are

To configure programs and services Home Manager must write various things to your home directory. To prevent overwriting any existing files when switching to a new generation, Home Manager will attempt to detect collisions between existing files and generated files. If any such collision is detected the activation will terminate before changing anything on your computer.

For example, suppose you have a wonderful, painstakingly created ~/.config/git/config and add

{
  # …

  programs.git = {
    enable = true;
    userName = "Jane Doe";
    userEmail = "jane.doe@example.org";
  };

  # …
}

to your configuration. Attempting to switch to the generation will then result in

$ home-manager switch
…
Activating checkLinkTargets
Existing file '/home/jdoe/.config/git/config' is in the way
Please move the above files and try again

Home Manager includes a number of services intended to run in a graphical session, for example xscreensaver and dunst. Unfortunately, such services will not be started automatically unless you let Home Manager start your X session. That is, you have something like

{
  # …

  services.xserver.enable = true;

  # …
}

in your system configuration and

{
  # …

  xsession.enable = true;
  xsession.windowManager.command = "…";

  # …
}

in your Home Manager configuration.

If you have installed Home Manager using the Nix channel method then updating Home Manager is done by first updating the channel. You can then switch to the updated Home Manager environment.

$ nix-channel --update
…
unpacking channels...
$ home-manager switch

To prepare an initial Home Manager configuration for your logged in user, you can run the Home Manager init command directly from its flake.

For example, if you are using the unstable version of Nixpkgs or NixOS, then to generate and activate a basic configuration run the command

$ nix run home-manager/master -- init --switch

For Nixpkgs or NixOS version 23.11 run

$ nix run home-manager/release-23.11 -- init --switch

This will generate a flake.nix and a home.nix file in ~/.config/home-manager, creating the directory if it does not exist.

If you omit the --switch option then the activation will not happen. This is useful if you want to inspect and edit the configuration before activating it.

$ nix run home-manager/$branch -- init
$ # Edit files in ~/.config/home-manager
$ nix run home-manager/$branch -- init --switch

Where $branch is one of master or release-23.11.

After the initial activation has completed successfully then building and activating your flake-based configuration is as simple as

$ home-manager switch

It is possible to override the default configuration directory, if you want. For example,

$ nix run home-manager/$branch -- init --switch ~/hmconf
$ # And after the initial activation.
$ home-manager switch --flake ~/hmconf

To use Home Manager as a NixOS module, a bare-minimum flake.nix would be as follows:

{
  description = "NixOS configuration";

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

  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.users.jdoe = import ./home.nix;

            # Optionally, use home-manager.extraSpecialArgs to pass
            # arguments to home.nix
          }
        ];
      };
    };
  };
}

The Home Manager configuration is then part of the NixOS configuration and is automatically rebuilt with the system when using the appropriate command for the system, such as nixos-rebuild switch --flake <flake-uri>.

You can use the above flake.nix as a template in /etc/nixos by

$ nix flake new /etc/nixos -t github:nix-community/home-manager#nixos

The flake-based setup of the Home Manager nix-darwin module is similar to that of NixOS. The flake.nix would be:

{
  description = "Darwin configuration";

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

  outputs = inputs@{ nixpkgs, home-manager, darwin, ... }: {
    darwinConfigurations = {
      hostname = darwin.lib.darwinSystem {
        system = "x86_64-darwin";
        modules = [
          ./configuration.nix
          home-manager.darwinModules.home-manager
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.users.jdoe = import ./home.nix;

            # Optionally, use home-manager.extraSpecialArgs to pass
            # arguments to home.nix
          }
        ];
      };
    };
  };
}

and it is also rebuilt with the nix-darwin generations. The rebuild command here may be darwin-rebuild switch --flake <flake-uri>.

You can use the above flake.nix as a template in ~/.config/darwin by

$ nix flake new ~/.config/darwin -t github:nix-community/home-manager#nix-darwin

Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types dagOf and gvariant that are used, for example, by programs.ssh.matchBlocks and dconf.settings.

If you have not previously forked Home Manager then you need to do that first. Have a look at GitHub’s Fork a repo for instructions on how to do this.

Once you have a fork of Home Manager you should create a branch starting at the most recent master branch. Give your branch a reasonably descriptive name. Commit your changes to this branch and when you are happy with the result and it fulfills Guidelines then push the branch to GitHub and create a pull request.

Assuming your clone is at $HOME/devel/home-manager then you can make the home-manager command use it by either

The first option is good if you only temporarily want to use your clone.

If your contribution satisfy the following rules then there is a good chance it will be merged without too much trouble. The rules are enforced by the Home Manager maintainers and to a lesser extent the Home Manager CI system.

If you are uncertain how these rules affect the change you would like to make then feel free to start a discussion in the #home-manager IRC channel, ideally before you start developing.

$ nix-build -A docs.html
$ xdg-open ./result/share/doc/home-manager/index.html

$ nix-build -A docs.manPages
$ man ./result/share/man/man5/home-configuration.nix.5.gz

{component}: {description}

{long description}

    starship: allow running in Emacs if vterm is used

    The vterm buffer is backed by libvterm and can handle Starship prompts
    without issues.

Home Manager includes a system for presenting news to the user. When making a change you, therefore, have the option to also include an associated news entry. In general, a news entry should only be added for truly noteworthy news. For example, a bug fix or new option does generally not need a news entry.

If you do have a change worthy of a news entry then please add one in news.nix but you should follow some basic guidelines:

Home Manager includes a basic test suite and it is highly recommended to include at least one test when adding a module. Tests are typically in the form of "golden tests" where, for example, a generated configuration file is compared to a known correct file.

It is relatively easy to create tests by modeling the existing tests, found in the tests project directory. For a full reference to the functions available in test scripts, you can look at NMT’s bash-lib.

The full Home Manager test suite can be run by executing

$ nix-shell --pure tests -A run.all

in the project root. List all test cases through

$ nix-shell --pure tests -A list

and run an individual test, for example alacritty-empty-settings, through

$ nix-shell --pure tests -A run.alacritty-empty-settings

However, those invocations will impurely source the system’s nixpkgs, and may cause failures. To run against the nixpkgs from the flake.lock, use instead e.g.

$ nix develop --ignore-environment .#all

Home Manager currently installs packages into the user environment, precisely as if the packages were installed through nix-env --install. This means that you will get a collision error if your Home Manager configuration attempts to install a package that you already have installed manually, that is, packages that shows up when you run nix-env --query.

For example, imagine you have the hello package installed in your environment

$ nix-env --query
hello-2.10

and your Home Manager configuration contains

home.packages = [ pkgs.hello ];

Then attempting to switch to this configuration will result in an error similar to

$ home-manager switch
these derivations will be built:
  /nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-home-manager-path.drv
[…]
Activating installPackages
replacing old ‘home-manager-path’
installing ‘home-manager-path’
building path(s) ‘/nix/store/b5c0asjz9f06l52l9812w6k39ifr49jj-user-environment’
Wide character in die at /nix/store/64jc9gd2rkbgdb4yjx3nrgc91bpjj5ky-buildenv.pl line 79.
collision between ‘/nix/store/fmwa4axzghz11cnln5absh31nbhs9lq1-home-manager-path/bin/hello’ and ‘/nix/store/c2wyl8b9p4afivpcz8jplc9kis8rj36d-hello-2.10/bin/hello’; use ‘nix-env --set-flag priority NUMBER PKGNAME’ to change the priority of one of the conflicting packages
builder for ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed with exit code 2
error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed

The solution is typically to uninstall the package from the environment using nix-env --uninstall and reattempt the Home Manager generation switch.

You could also opt to unistall all of the packages from your profile with nix-env --uninstall '*'.

Home Manager is only able to set session variables automatically if it manages your Bash, Z shell, or fish shell configuration. To enable such management you use programs.bash.enable, programs.zsh.enable, or programs.fish.enable.

If you don’t want to let Home Manager manage your shell then you will have to manually source the ~/.nix-profile/etc/profile.d/hm-session-vars.sh file in an appropriate way. In Bash and Z shell this can be done by adding

. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"

to your .profile and .zshrc files, respectively. The hm-session-vars.sh file should work in most Bourne-like shells. For fish shell, it is possible to source it using the foreign-env plugin

fenv source "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" > /dev/null

A typical way to prepare a repository of configurations for multiple logins and machines is to prepare one "top-level" file for each unique combination.

For example, if you have two machines, called "kronos" and "rhea" on which you want to configure your user "jane" then you could create the files

in your repository. On the kronos and rhea machines you can then make ~jane/.config/home-manager/home.nix be a symbolic link to the corresponding file in your configuration repository.

The kronos-jane.nix and rhea-jane.nix files follow the format

{ ... }:

{
  imports = [ ./common.nix ];

  # Various options that are specific for this machine/user.
}

while the common.nix file contains configuration shared across the two logins. Of course, instead of just a single common.nix file you can have multiple ones, even one per program or service.

You can get some inspiration from the Post your home-manager home.nix file! Reddit thread.

You are most likely trying to configure something that uses dconf but the DBus session is not aware of the dconf service. The full error you might get is

error: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files

or

error: GDBus.Error:org.freedesktop.systemd1.NoSuchUnit: Unit dconf.service not found.

The solution on NixOS is to add

programs.dconf.enable = true;

to your system configuration.

If you are using a stable version of Nixpkgs but would like to install some particular packages from Nixpkgs unstable – or some other channel – then you can import the unstable Nixpkgs and refer to its packages within your configuration. Something like

{ pkgs, config, ... }:

let

  pkgsUnstable = import <nixpkgs-unstable> {};

in

{
  home.packages = [
    pkgsUnstable.foo
  ];

  # …
}

should work provided you have a Nix channel called nixpkgs-unstable.

You can add the nixpkgs-unstable channel by running

$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs-unstable
$ nix-channel --update

Note, the package will not be affected by any package overrides, overlays, etc.

By default Home Manager will install the package provided by your chosen nixpkgs channel but occasionally you might end up needing to change this package. This can typically be done in two ways.