fork/home-manager

git clone https://git.julia.blue/fork/home-manager

Robert Helgessondocs: fix option nameae631b0b

master
10.8 KiB355 linesraw
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, ... }: {
156  home.packages = [ pkgs.atool pkgs.httpie ];
157  programs.bash.enable = true;
158
159  # The state version is required and should stay at the version you
160  # originally installed.
161  home.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 = {
279  name = "eve";
280  home = "/Users/eve";
281}
282home-manager.users.eve = { pkgs, ... }: {
283  home.packages = [ pkgs.atool pkgs.httpie ];
284  programs.bash.enable = true;
285
286  # The state version is required and should stay at the version you
287  # originally installed.
288  home.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.