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

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. 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 21.05 channel, you can run

# nix-channel --add https://github.com/nix-community/home-manager/archive/release-21.05.tar.gz home-manager
# 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;
};

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

home-manager.useUserPackages = true;

home-manager.useGlobalPkgs = true;

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 21.05 channel, you can run

# nix-channel --add https://github.com/nix-community/home-manager/archive/release-21.05.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;
};

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

home-manager.useUserPackages = true;

home-manager.useGlobalPkgs = true;

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 Section 3.2, “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

The commits in your pull request should be reasonably self-contained, that is, each commit should make sense in isolation. In particular, you will be asked to amend any commit that introduces syntax errors or similar problems even if they are fixed in a later commit.

The commit messages should follow the seven rules. We also ask you to include the affected code component or module in the first line. That is, a commit message should follow the template

{component}: {description}

{long description}

where {component} refers to the code component (or module) your change affects, {description} is a very brief description of your change, and {long description} is an optional clarifying description. As a rare exception, if there is no clear component, or your change affects many components, then the {component} part is optional. See Example 3.1, “Compliant commit message” for a commit message that fulfills these requirements.

starship: allow running in Emacs if vterm is used

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

Finally, when adding a new module, say programs/foo.nix, we use the fixed commit format foo: add module. You can, of course, still include a long description if you wish.

The code in Home Manager is formatted by the nixfmt tool and the formatting is checked in the pull request tests. Run the format tool inside the project repository before submitting your pull request.

Keep lines at a reasonable width, ideally 80 characters or less. This also applies to string literals.

We prefer lowerCamelCase for variable and attribute names with the accepted exception of variables directly referencing packages in Nixpkgs which use a hyphenated style. For example, the Home Manager option services.gpg-agent.enableSshSupport references the gpg-agent package in Nixpkgs.

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.

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

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. 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/nixpkgs/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 the GTK or Gnome Terminal 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

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.