fork/home-manager
git clone https://git.julia.blue/fork/home-manager
33ccc5c2
master
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 = { 41package = pkgs.nixFlakes; 42extraOptions = '' 43experimental-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{ 142description = "NixOS configuration"; 143 144inputs = { 145nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; 146home-manager.url = "github:nix-community/home-manager"; 147home-manager.inputs.nixpkgs.follows = "nixpkgs"; 148}; 149 150outputs = inputs@{ nixpkgs, home-manager, ... }: { 151nixosConfigurations = { 152hostname = nixpkgs.lib.nixosSystem { 153system = "x86_64-linux"; 154modules = [ 155./configuration.nix 156home-manager.nixosModules.home-manager 157{ 158home-manager.useGlobalPkgs = true; 159home-manager.useUserPackages = true; 160home-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{ 190description = "Darwin configuration"; 191 192inputs = { 193nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; 194darwin.url = "github:lnl7/nix-darwin"; 195darwin.inputs.nixpkgs.follows = "nixpkgs"; 196home-manager.url = "github:nix-community/home-manager"; 197home-manager.inputs.nixpkgs.follows = "nixpkgs"; 198}; 199 200outputs = inputs@{ nixpkgs, home-manager, darwin, ... }: { 201darwinConfigurations = { 202hostname = darwin.lib.darwinSystem { 203system = "x86_64-darwin"; 204modules = [ 205./configuration.nix 206home-manager.darwinModules.home-manager 207{ 208home-manager.useGlobalPkgs = true; 209home-manager.useUserPackages = true; 210home-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