fork/home-manager

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

Robert HelgessonSwitch stable branch to release-23.0533ccc5c2

master
7.0 KiB228 linesraw
1[[ch-nix-flakes]]
2== Nix Flakes
3
4:nixos-wiki-flakes: https://nixos.wiki/wiki/Flakes
5
6Home Manager is compatible with {nixos-wiki-flakes}[Nix Flakes]. But
7please be aware that the support it is still experimental and may
8change in backwards incompatible ways.
9
10Just like in the standard installation you can use the Home Manager
11flake in three ways:
12
131. Using the standalone `home-manager` tool. For platforms other than
14NixOS and Darwin, this is the only available choice. It is also
15recommended for people on NixOS or Darwin that want to manage their
16home directory independently of the system as a whole. See
17<<sec-flakes-standalone>> for instructions on how to perform this
18installation.
19
202. As a module within a NixOS system configuration. This allows the
21user profiles to be built together with the system when running
22`nixos-rebuild`. See <<sec-flakes-nixos-module>> for a description of
23this setup.
24
253. As a module within a {nix-darwin}[nix-darwin] system configuration.
26This allows the user profiles to be built together with the system
27when running `darwin-rebuild`. See <<sec-flakes-nix-darwin-module>>
28for a description of this setup.
29
30[[sec-flakes-prerequisites]]
31=== Prerequisites
32
33* Install Nix 2.4 or later, or have it in `nix-shell`.
34
35* Enable experimental features `nix-command` and `flakes`.
36+
37** When using NixOS, add the following to your `configuration.nix` and rebuild your system.
38+
39[source,nix]
40nix = {
41  package = pkgs.nixFlakes;
42  extraOptions = ''
43    experimental-features = nix-command flakes
44  '';
45};
46+
47** If you are not using NixOS, add the following to `nix.conf` (located at `~/.config/nix/` or `/etc/nix/nix.conf`).
48+
49[source,bash]
50experimental-features = nix-command flakes
51+
52You may need to restart the Nix daemon with, for example, `sudo systemctl restart nix-daemon.service`.
53+
54** Alternatively, you can enable flakes on a per-command basis with the following additional flags to `nix` and `home-manager`:
55+
56[source,console]
57----
58$ nix --extra-experimental-features "nix-command flakes" <sub-commands>
59$ home-manager --extra-experimental-features "nix-command flakes" <sub-commands>
60----
61
62* Prepare your Home Manager configuration (`home.nix`).
63+
64Unlike the channel-based setup,
65`home.nix` will be evaluated when the flake is built,
66so it must be present before bootstrap of Home Manager from the flake.
67See <<sec-usage-configuration>> for introduction about
68writing a Home Manager configuration.
69
70[[sec-flakes-standalone]]
71=== Standalone setup
72
73To prepare an initial Home Manager configuration for your logged in user,
74you can run the Home Manager `init` command directly from its flake.
75
76For example, if you are using the unstable version of Nixpkgs or NixOS,
77then to generate and activate a basic configuration run the command
78
79[source,console]
80$ nix run home-manager/master -- init --switch
81
82For Nixpkgs or NixOS version 23.05 run
83
84[source,console]
85$ nix run home-manager/release-23.05 -- init --switch
86
87This will generate a `flake.nix` and a `home.nix` file in
88`~/.config/home-manager`, creating the directory if it does not exist.
89
90If you omit the `--switch` option then the activation will not happen.
91This is useful if you want to inspect and edit the configuration before activating it.
92
93[source,console]
94----
95$ nix run home-manager/$branch -- init
96$ # Edit files in ~/.config/home-manager
97$ nix run home-manager/$branch -- init --switch
98----
99
100Where `$branch` is one of `master` or `release-23.05`.
101
102After the initial activation has completed successfully then building
103and activating your flake-based configuration is as simple as
104
105[source,console]
106$ home-manager switch
107
108It is possible to override the default configuration directory, if you want.
109For example,
110
111[source,console]
112----
113$ nix run home-manager/$branch -- init --switch ~/hmconf
114$ # And after the initial activation.
115$ home-manager switch --flake ~/hmconf
116----
117
118[NOTE]
119====
120The flake inputs are not automatically updated by Home Manager.
121You need to use the standard `nix flake update` command for that.
122
123If you only want to update a single flake input,
124then the command `nix flake lock --update-input <input>` can be used.
125
126You can also pass flake-related options
127such as `--recreate-lock-file` or `--update-input <input>`
128to `home-manager` when building or switching,
129and these options will be forwarded to `nix build`.
130See the {nixos-wiki-flakes}[NixOS Wiki page] for details.
131====
132
133[[sec-flakes-nixos-module]]
134=== NixOS module
135
136To use Home Manager as a NixOS module,
137a bare-minimum `flake.nix` would be as follows:
138
139[source,nix]
140----
141{
142  description = "NixOS configuration";
143
144  inputs = {
145    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
146    home-manager.url = "github:nix-community/home-manager";
147    home-manager.inputs.nixpkgs.follows = "nixpkgs";
148  };
149
150  outputs = inputs@{ nixpkgs, home-manager, ... }: {
151    nixosConfigurations = {
152      hostname = nixpkgs.lib.nixosSystem {
153        system = "x86_64-linux";
154        modules = [
155          ./configuration.nix
156          home-manager.nixosModules.home-manager
157          {
158            home-manager.useGlobalPkgs = true;
159            home-manager.useUserPackages = true;
160            home-manager.users.jdoe = import ./home.nix;
161
162            # Optionally, use home-manager.extraSpecialArgs to pass
163            # arguments to home.nix
164          }
165        ];
166      };
167    };
168  };
169}
170----
171
172The Home Manager configuration is then part of the NixOS configuration
173and is automatically rebuilt with the system when using the appropriate command
174for the system, such as `nixos-rebuild switch --flake <flake-uri>`.
175
176You can use the above `flake.nix` as a template in `/etc/nixos` by
177
178[source,console]
179$ nix flake new /etc/nixos -t github:nix-community/home-manager#nixos
180
181[[sec-flakes-nix-darwin-module]]
182=== nix-darwin module
183
184The flake-based setup of the Home Manager nix-darwin module
185is similar to that of NixOS. The `flake.nix` would be:
186
187[source,nix]
188----
189{
190  description = "Darwin configuration";
191
192  inputs = {
193    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
194    darwin.url = "github:lnl7/nix-darwin";
195    darwin.inputs.nixpkgs.follows = "nixpkgs";
196    home-manager.url = "github:nix-community/home-manager";
197    home-manager.inputs.nixpkgs.follows = "nixpkgs";
198  };
199
200  outputs = inputs@{ nixpkgs, home-manager, darwin, ... }: {
201    darwinConfigurations = {
202      hostname = darwin.lib.darwinSystem {
203        system = "x86_64-darwin";
204        modules = [
205          ./configuration.nix
206          home-manager.darwinModules.home-manager
207          {
208            home-manager.useGlobalPkgs = true;
209            home-manager.useUserPackages = true;
210            home-manager.users.jdoe = import ./home.nix;
211
212            # Optionally, use home-manager.extraSpecialArgs to pass
213            # arguments to home.nix
214          }
215        ];
216      };
217    };
218  };
219}
220----
221
222and it is also rebuilt with the nix-darwin generations.
223The rebuild command here may be `darwin-rebuild switch --flake <flake-uri>`.
224
225You can use the above `flake.nix` as a template in `~/.config/darwin` by
226
227[source,console]
228$ nix flake new ~/.config/darwin -t github:nix-community/home-manager#nix-darwin