fork/home-manager
git clone https://git.julia.blue/fork/home-manager
ae631b0b
master
1[[ch-installation]] 2== Installing Home Manager 3 4: nix-darwin : https://github.com/LnL7/nix-darwin/ 5:nixos-wiki-flakes: https://nixos.wiki/wiki/Flakes 6 7Home Manager can be used in three primary ways: 8 91. Using the standalone `home-manager` tool. For platforms other than 10NixOS and Darwin, this is the only available choice. It is also 11recommended for people on NixOS or Darwin that want to manage their 12home directory independently of the system as a whole. See 13<<sec-install-standalone>> for instructions on how to perform this 14installation. 15 162. As a module within a NixOS system configuration. This allows the 17user profiles to be built together with the system when running 18`nixos-rebuild`. See <<sec-install-nixos-module>> for a description of 19this setup. 20 213. As a module within a {nix-darwin}[nix-darwin] system configuration. 22This allows the user profiles to be built together with the system 23when running `darwin-rebuild`. See <<sec-install-nix-darwin-module>> 24for a description of this setup. 25 26[ NOTE ] 27In this chapter we describe how to install Home Manager in the 28standard way using channels. If you prefer to use 29{nixos-wiki-flakes}[Nix Flakes] then please see the instructions in 30<<ch-nix-flakes>>. 31 32[[sec-install-standalone]] 33=== Standalone installation 34 35: nix-allowed-users : https://nixos.org/nix/manual/#conf-allowed-users 36: nixos-allowed-users : https://nixos.org/manual/nixos/stable/options.html#opt-nix.settings.allowed-users 37: bash : https://www.gnu.org/software/bash/ 38:zsh: http://zsh.sourceforge.net/ 39:fish: https://fishshell.com 40: plugin-foreign-env : https://github.com/oh-my-fish/plugin-foreign-env 41: babelfish : https://github.com/bouk/babelfish 42 431. Make sure you have a working Nix installation. Specifically, make 44sure that your user is able to build and install Nix packages. For 45example, you should be able to successfully run a command like 46`nix-instantiate '<nixpkgs>' -A hello` without having to switch to the 47root user. For a multi-user install of Nix this means that your user 48must be covered by the {nix-allowed-users}[`allowed-users`] Nix 49option. On NixOS you can control this option using the 50{nixos-allowed-users}[`nix.settings.allowed-users`] system option. 51 522. Add the appropriate Home Manager channel. If you are following 53Nixpkgs master or an unstable channel you can run 54+ 55[ source,console ] 56---- 57$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager 58$ nix-channel --update 59---- 60+ 61and if you follow a Nixpkgs version 23.05 channel you can run 62+ 63[ source,console ] 64---- 65$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager 66$ nix-channel --update 67---- 68 693. Run the Home Manager installation command and create the first Home 70Manager generation: 71+ 72[ source,console ] 73$ nix-shell '<home-manager>' -A install 74+ 75Once finished, Home Manager should be active and available in your 76user environment. 77 784. If you do not plan on having Home Manager manage your shell 79configuration then you must source the 80+ 81[ source,bash ] 82$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh 83+ 84file in your shell configuration. Alternatively source 85+ 86[ source,bash ] 87/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh 88+ 89when managing home configuration together with system configuration. 90+ 91This file can be sourced directly by POSIX.2-like shells such as 92{bash}[Bash] or {zsh}[Z shell]. {fish}[Fish] users can use utilities 93such as {plugin-foreign-env}[foreign-env] or {babelfish}[babelfish]. 94+ 95For example, if you use Bash then add 96+ 97[ source,bash ] 98---- 99. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" 100---- 101+ 102to your `~/.profile` file. 103 104If instead of using channels you want to run Home Manager from a Git 105checkout of the repository then you can use the 106<<opt-programs.home-manager.path>> option to specify the absolute path 107to the repository. 108 109Once installed you can see <<ch-usage>> for a more detailed 110description of Home Manager and how to use it. 111 112[[sec-install-nixos-module]] 113=== NixOS module 114 115Home Manager provides a NixOS module that allows you to prepare user 116environments directly from the system configuration file, which often 117is more convenient than using the `home-manager` tool. It also opens 118up additional possibilities, for example, to automatically configure 119user environments in NixOS declarative containers or on systems 120deployed through NixOps. 121 122To make the NixOS module available for use you must `import` it into 123your system configuration. This is most conveniently done by adding a 124Home Manager channel to the root user. For example, if you are 125following Nixpkgs master or an unstable channel, you can run 126 127[ source,console ] 128---- 129$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager 130$ sudo nix-channel --update 131---- 132 133and if you follow a Nixpkgs version 23.05 channel, you can run 134 135[ source,console ] 136---- 137$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager 138$ sudo nix-channel --update 139---- 140 141It is then possible to add 142 143[ source,nix ] 144imports = [ <home-manager/nixos> ]; 145 146to your system `configuration.nix` file, which will introduce a new 147NixOS option called `home-manager.users` whose type is an attribute 148set that maps user names to Home Manager configurations. 149 150For example, a NixOS configuration may include the lines 151 152[ source,nix ] 153---- 154users.users.eve.isNormalUser = true; 155home-manager.users.eve = { pkgs, ... }: { 156home.packages = [ pkgs.atool pkgs.httpie ]; 157programs.bash.enable = true; 158 159# The state version is required and should stay at the version you 160# originally installed. 161home.stateVersion = "23.05"; 162}; 163---- 164 165and after a `sudo nixos-rebuild switch` the user eve's environment should 166include a basic Bash configuration and the packages atool and httpie. 167 168[NOTE] 169==== 170If `nixos-rebuild switch` does not result in the environment you expect, 171you can take a look at the output of the Home Manager activation script output using 172 173[ source,console ] 174$ systemctl status "home-manager-$USER.service" 175==== 176 177If you do not plan on having Home Manager manage your shell 178configuration then you must add either 179 180[ source,bash ] 181---- 182. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" 183---- 184 185or 186 187[ source,bash ] 188---- 189. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh" 190---- 191 192to your shell configuration, depending on whether 193<<nixos-opt-home-manager.useUserPackages>> is enabled. This file can 194be sourced directly by POSIX.2-like shells such as {bash}[Bash] or 195{zsh}[Z shell]. {fish}[Fish] users can use utilities such as 196{plugin-foreign-env}[foreign-env] or {babelfish}[babelfish]. 197 198[NOTE] 199==== 200By default packages will be installed to `$HOME/.nix-profile` but they 201can be installed to `/etc/profiles` if 202 203[ source,nix ] 204home-manager.useUserPackages = true; 205 206is added to the system configuration. This is necessary if, for 207example, you wish to use `nixos-rebuild build-vm`. This option may 208become the default value in the future. 209==== 210 211[NOTE] 212==== 213By default, Home Manager uses a private `pkgs` instance that is 214configured via the `home-manager.users.<name>.nixpkgs` options. To 215instead use the global `pkgs` that is configured via the system level 216`nixpkgs` options, set 217 218[ source,nix ] 219home-manager.useGlobalPkgs = true; 220 221This saves an extra Nixpkgs evaluation, adds consistency, and removes 222the dependency on `NIX_PATH`, which is otherwise used for importing 223Nixpkgs. 224==== 225 226[NOTE] 227==== 228Home Manager will pass `osConfig` as a module argument to any modules 229you create. This contains the system's NixOS configuration. 230 231[ source,nix ] 232{ lib, pkgs, osConfig, ... }: 233==== 234 235Once installed you can see <<ch-usage>> for a more detailed 236description of Home Manager and how to use it. 237 238[[sec-install-nix-darwin-module]] 239=== nix-darwin module 240 241Home Manager provides a module that allows you to prepare user 242environments directly from the {nix-darwin}[nix-darwin] configuration 243file, which often is more convenient than using the `home-manager` 244tool. 245 246To make the NixOS module available for use you must `import` it into 247your system configuration. This is most conveniently done by adding a 248Home Manager channel. For example, if you are following Nixpkgs master 249or an unstable channel, you can run 250 251[ source,console ] 252---- 253$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager 254$ nix-channel --update 255---- 256 257and if you follow a Nixpkgs version 23.05 channel, you can run 258 259[ source,console ] 260---- 261$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager 262$ nix-channel --update 263---- 264 265It is then possible to add 266 267[ source,nix ] 268imports = [ <home-manager/nix-darwin> ]; 269 270to your nix-darwin `configuration.nix` file, which will introduce a 271new NixOS option called `home-manager` whose type is an attribute set 272that maps user names to Home Manager configurations. 273 274For example, a nix-darwin configuration may include the lines 275 276[ source,nix ] 277---- 278users.users.eve = { 279name = "eve"; 280home = "/Users/eve"; 281} 282home-manager.users.eve = { pkgs, ... }: { 283home.packages = [ pkgs.atool pkgs.httpie ]; 284programs.bash.enable = true; 285 286# The state version is required and should stay at the version you 287# originally installed. 288home.stateVersion = "23.05"; 289}; 290---- 291 292and after a `darwin-rebuild switch` the user eve's environment 293should include a basic Bash configuration and the packages atool and 294httpie. 295 296If you do not plan on having Home Manager manage your shell 297configuration then you must add either 298 299[ source,bash ] 300---- 301. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" 302---- 303 304or 305 306[ source,bash ] 307---- 308. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh" 309---- 310 311to your shell configuration, depending on whether 312<<nix-darwin-opt-home-manager.useUserPackages>> is enabled. This file 313can be sourced directly by POSIX.2-like shells such as {bash}[Bash] or 314{zsh}[Z shell]. {fish}[Fish] users can use utilities such as 315{plugin-foreign-env}[foreign-env] or {babelfish}[babelfish]. 316 317[NOTE] 318==== 319By default user packages will not be ignored in favor of 320`environment.systemPackages`, but they will be installed to 321`/etc/profiles/per-user/$USERNAME` if 322 323[ source,nix ] 324home-manager.useUserPackages = true; 325 326is added to the nix-darwin configuration. This option may become the 327default value in the future. 328==== 329 330[NOTE] 331==== 332By default, Home Manager uses a private `pkgs` instance that is 333configured via the `home-manager.users.<name>.nixpkgs` options. To 334instead use the global `pkgs` that is configured via the system level 335`nixpkgs` options, set 336 337[ source,nix ] 338home-manager.useGlobalPkgs = true; 339 340This saves an extra Nixpkgs evaluation, adds consistency, and removes 341the dependency on `NIX_PATH`, which is otherwise used for importing 342Nixpkgs. 343==== 344 345[NOTE] 346==== 347Home Manager will pass `osConfig` as a module argument to any modules 348you create. This contains the system's nix-darwin configuration. 349 350[ source,nix ] 351{ lib, pkgs, osConfig, ... }: 352==== 353 354Once installed you can see <<ch-usage>> for a more detailed 355description of Home Manager and how to use it.