[[ch-installation]] == Installing Home Manager :nix-darwin: https://github.com/LnL7/nix-darwin/ 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 <> 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 <> for a description of this setup. 3. As a module within a {nix-darwin}[nix-darwin] system configuration. This allows the user profiles to be built together with the system when running `darwin-rebuild`. See <> for a description of this setup. [[sec-install-standalone]] === Standalone installation :nix-allowed-users: https://nixos.org/nix/manual/#conf-allowed-users :nixos-allowed-users: https://nixos.org/nixos/manual/options.html#opt-nix.allowedUsers 1. Make sure you have a working Nix installation. Specifically, 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 '' -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 {nix-allowed-users}[`allowed-users`] Nix option. On NixOS you can control this option using the {nixos-allowed-users}[`nix.allowedUsers`] system option. 2. Add the Home Manager channel that you wish to follow. If you are following Nixpkgs master or an unstable channel then this is done by running + [source,console] ---- $ 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 + [source,console] ---- $ nix-channel --add https://github.com/nix-community/home-manager/archive/release-21.05.tar.gz home-manager $ nix-channel --update ---- + 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 + [source,bash] export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH + to your shell (see https://github.com/NixOS/nix/issues/2033[nix#2033]). 3. Run the Home Manager installation command and create the first Home Manager generation: + [source,console] $ nix-shell '' -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 + [source,bash] $HOME/.nix-profile/etc/profile.d/hm-session-vars.sh + file in your shell configuration. Alternatively source + [source,bash] /etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh + when managing home configuration together with system configuration. + Unfortunately, we currently only support POSIX.2-like shells such as https://www.gnu.org/software/bash/[Bash] or http://zsh.sourceforge.net/[Z shell]. + For example, if you use Bash then add + [source,bash] ---- . "$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 <> option to specify the absolute path to the repository. [[sec-install-nixos-module]] === 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, if you are following Nixpkgs master or an unstable channel, you can run [source,console] ---- # 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 [source,console] ---- # 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 [source,nix] imports = [ ]; 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 [source,nix] ---- 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 [source,nix] 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. ==== [NOTE] ==== By default, Home Manager uses a private `pkgs` instance that is configured via the `home-manager.users..nixpkgs` options. To instead use the global `pkgs` that is configured via the system level `nixpkgs` options, set [source,nix] home-manager.useGlobalPkgs = true; This saves an extra Nixpkgs evaluation, adds consistency, and removes the dependency on `NIX_PATH`, which is otherwise used for importing Nixpkgs. ==== [[sec-install-nix-darwin-module]] === nix-darwin module Home Manager provides a module that allows you to prepare user environments directly from the {nix-darwin}[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 [source,console] ---- # 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 [source,console] ---- # 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 [source,nix] imports = [ ]; 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 [source,nix] ---- 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. [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 [source,nix] home-manager.useUserPackages = true; is added to the nix-darwin configuration. This option may become the default value in the future. ==== [NOTE] ==== By default, Home Manager uses a private `pkgs` instance that is configured via the `home-manager.users..nixpkgs` options. To instead use the global `pkgs` that is configured via the system level `nixpkgs` options, set [source,nix] home-manager.useGlobalPkgs = true; This saves an extra Nixpkgs evaluation, adds consistency, and removes the dependency on `NIX_PATH`, which is otherwise used for importing Nixpkgs. ====