Home Manager Manual


Preface
1. Installing Home Manager
1.1. Standalone installation
1.2. NixOS module
1.3. nix-darwin module
A. Configuration Options
B. Tools
home-manager — reconfigure a user environment
C. Release Notes
C.1. Release 20.03 (unreleased)
C.1.1. Highlights
C.1.2. State Version Changes
C.2. Release 19.09
C.2.1. Highlights
C.2.2. State Version Changes
C.3. Release 19.03
C.3.1. Highlights
C.3.2. State Version Changes
C.4. Release 18.09

Preface

This manual will eventually describes how to install, use, and extend Home Manager.

If you encounter problems or bugs then please report them on the Home Manager issue tracker.

Note

Commands prefixed with # have to be run as root, either requiring to login as root user or temporarily switching to it using sudo for example.

Chapter 1. Installing Home Manager

Home Manager can be used in three primary ways:

  1. Using the standalone home-manager tool. For platforms other than NixOS and Darwin, this is the only available choice. It is also recommended for people on NixOS or Darwin that want to manage their home directory independent of the system as a whole. See Section 1.1, “Standalone installation” for instructions on how to perform this installation.

  2. As a module within a NixOS system configuration. This allows the user profiles to be built together with the system when running nixos-rebuild. See Section 1.2, “NixOS module” for a description of this setup.

  3. As a module within a nix-darwin system configuration. This allows the user profiles to be built together with the system when running darwin-rebuild. See Section 1.3, “nix-darwin module” for a description of this setup.

1.1. Standalone installation

  1. Make sure you have a working Nix installation. If you are not using NixOS then it may be necessary to run

    $ mkdir -m 0755 -p /nix/var/nix/{profiles,gcroots}/per-user/$USER
    

    since Home Manager uses these directories to manage your profile generations. On NixOS these should already be available.

    Also make sure that your user is able to build and install Nix packages. For example, you should be able to successfully run a command like nix-instantiate '<nixpkgs>' -A hello without having to switch to the root user. For a multi-user install of Nix this means that your user must be covered by the allowed-users Nix option. On NixOS you can control this option using the nix.allowedUsers system option.

  2. Add the Home Manager channel that you wish to follow. This is done by running

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

    if you are following Nixpkgs master or an unstable channel and

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

    if you follow a Nixpkgs version 19.09 channel.

    On NixOS you may need to log out and back in for the channel to become available. On non-NixOS you may have to add

    export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH
    

    to your shell (see nix#2033).

  3. Run the Home Manager installation command and create the first Home Manager generation:

    $ nix-shell '<home-manager>' -A install
    

    Once finished, Home Manager should be active and available in your user environment.

  4. If you do not plan on having Home Manager manage your shell configuration then you must source the

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

    file in your shell configuration. Unfortunately, we currently only support POSIX.2-like shells such as Bash or Z shell.

    For example, if you use Bash then add

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

    to your ~/.profile file.

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.

1.2. NixOS module

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

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

if you are following Nixpkgs master or an unstable channel and

# nix-channel --add https://github.com/rycee/home-manager/archive/release-19.09.tar.gz home-manager
# nix-channel --update

if you follow a Nixpkgs version 19.09 channel.

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.

Note

By default packages will be installed to $HOME/.nix-profile but they can be installed to /etc/profiles if

home-manager.useUserPackages = true;

is added to the system configuration. This is necessary if, for example, you wish to use nixos-rebuild build-vm. This option may become the default value in the future.

1.3. nix-darwin module

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

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

if you are following Nixpkgs master or an unstable channel and

# nix-channel --add https://github.com/rycee/home-manager/archive/release-19.09.tar.gz home-manager
# nix-channel --update

if you follow a Nixpkgs version 19.09 channel.

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

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.

Note

By default user packages will not be ignored in favor of environment.systemPackages, but they will be intalled to /etc/profiles/per-user/$USERNAME if

home-manager.useUserPackages = true;

is added to the nix-darwin configuration. This option may become the default value in the future.