mirror of
https://github.com/nix-community/home-manager
synced 2024-11-05 18:59:44 +01:00
c8cb60b8a1
The init command is essentially the old install script but integrated into the home-manager tool. This simplifies things slightly since we can use the existing code infrastructure. The init command is Nix flake aware in the sense that, if we detect that the user's Nix setup supports flakes, then we also create an initial `flake.nix` file. Finally, we update the installation instructions for the Nix flakes standalone setup to use the new init command. Zsh completion update provided by Anund <anundm@gmail.com>.
318 lines
9.6 KiB
Text
318 lines
9.6 KiB
Text
[[ch-nix-flakes]]
|
||
== Nix Flakes
|
||
|
||
:nixos-wiki-flakes: https://nixos.wiki/wiki/Flakes
|
||
|
||
Home Manager is compatible with {nixos-wiki-flakes}[Nix Flakes]. But
|
||
please be aware that the support it is still experimental and may
|
||
change in backwards incompatible ways.
|
||
|
||
Just like in the standard installation you can use the Home Manager
|
||
flake in three 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 independently of the system as a whole. See
|
||
<<sec-flakes-standalone>> 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 <<sec-flakes-nixos-module>> 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 <<sec-flakes-nix-darwin-module>>
|
||
for a description of this setup.
|
||
|
||
[[sec-flakes-prerequisites]]
|
||
=== Prerequisites
|
||
|
||
* Install Nix 2.4 or later, or have it in `nix-shell`.
|
||
|
||
* Enable experimental features `nix-command` and `flakes`.
|
||
+
|
||
** When using NixOS, add the following to your `configuration.nix` and rebuild your system.
|
||
+
|
||
[source,nix]
|
||
nix = {
|
||
package = pkgs.nixFlakes;
|
||
extraOptions = ''
|
||
experimental-features = nix-command flakes
|
||
'';
|
||
};
|
||
+
|
||
** If you are not using NixOS, add the following to `nix.conf` (located at `~/.config/nix/` or `/etc/nix/nix.conf`).
|
||
+
|
||
[source,bash]
|
||
experimental-features = nix-command flakes
|
||
+
|
||
You may need to restart the Nix daemon with, for example, `sudo systemctl restart nix-daemon.service`.
|
||
+
|
||
** Alternatively, you can enable flakes on a per-command basis with the following additional flags to `nix` and `home-manager`:
|
||
+
|
||
[source,console]
|
||
----
|
||
$ nix --extra-experimental-features "nix-command flakes" <sub-commands>
|
||
$ home-manager --extra-experimental-features "nix-command flakes" <sub-commands>
|
||
----
|
||
|
||
* Prepare your Home Manager configuration (`home.nix`).
|
||
+
|
||
Unlike the channel-based setup,
|
||
`home.nix` will be evaluated when the flake is built,
|
||
so it must be present before bootstrap of Home Manager from the flake.
|
||
See <<sec-usage-configuration>> for introduction about
|
||
writing a Home Manager configuration.
|
||
|
||
[[sec-flakes-standalone]]
|
||
=== Standalone setup
|
||
|
||
The installation procedure for the standalone version of Home Manager
|
||
is currently different for the unstable and stable branch.
|
||
Therefore, if you are tracking the Nixpkgs or NixOS unstable please go to
|
||
<<sec-flakes-standalone-unstable>>,
|
||
and if you track Nixpkgs or NixOS version 22.11 please go to
|
||
<<sec-flakes-standalone-stable>>.
|
||
|
||
[[sec-flakes-standalone-unstable]]
|
||
==== Unstable Version
|
||
|
||
To prepare an initial Home Manager configuration for your logged in user,
|
||
you can run the Home Manager `init` command directly from its flake.
|
||
|
||
For example, to generate and activate a basic configuration run the command
|
||
|
||
[source,console]
|
||
$ nix run home-manager/master -- init --switch
|
||
|
||
This will generate a `flake.nix` and a `home.nix` file in
|
||
`~/.config/home-manager`, creating the directory if it does not exist.
|
||
|
||
If you omit the `--switch` option then the activation will not happen.
|
||
This is useful if you want to inspect and edit the configuration before activating it.
|
||
|
||
[source,console]
|
||
----
|
||
$ nix run home-manager/master -- init
|
||
$ # Edit files in ~/.config/home-manager
|
||
$ nix run home-manager/master -- init --switch
|
||
----
|
||
|
||
After the initial activation has completed successfully then building
|
||
and activating your flake-based configuration is as simple as
|
||
|
||
[source,console]
|
||
$ home-manager switch
|
||
|
||
It is possible to override the default configuration directory, if you want.
|
||
For example,
|
||
|
||
[source,console]
|
||
----
|
||
$ nix run home-manager/master -- init --switch ~/hmconf
|
||
$ # And after the initial activation.
|
||
$ home-manager switch --flake ~/hmconf
|
||
----
|
||
|
||
[NOTE]
|
||
====
|
||
The flake inputs are not automatically updated by Home Manager.
|
||
You need to use the standard `nix flake update` command for that.
|
||
|
||
If you only want to update a single flake input,
|
||
then the command `nix flake lock --update-input <input>` can be used.
|
||
|
||
You can also pass flake-related options
|
||
such as `--recreate-lock-file` or `--update-input <input>`
|
||
to `home-manager` when building or switching,
|
||
and these options will be forwarded to `nix build`.
|
||
See the {nixos-wiki-flakes}[NixOS Wiki page] for details.
|
||
====
|
||
|
||
[[sec-flakes-standalone-stable]]
|
||
==== Version 22.11
|
||
|
||
1. Set up a flake with a `flake.nix` as follows:
|
||
+
|
||
[source,nix]
|
||
----
|
||
{
|
||
description = "Home Manager configuration of Jane Doe";
|
||
|
||
inputs = {
|
||
# Specify the source of Home Manager and Nixpkgs.
|
||
nixpkgs.url = "github:nixos/nixpkgs/nixos-22.11";
|
||
home-manager = {
|
||
url = "github:nix-community/home-manager/release-22.11";
|
||
inputs.nixpkgs.follows = "nixpkgs";
|
||
};
|
||
};
|
||
|
||
outputs = { nixpkgs, home-manager, ... }:
|
||
let
|
||
system = "x86_64-linux";
|
||
pkgs = nixpkgs.legacyPackages.${system};
|
||
in {
|
||
homeConfigurations.jdoe = home-manager.lib.homeManagerConfiguration {
|
||
inherit pkgs;
|
||
|
||
# Specify your home configuration modules here, for example,
|
||
# the path to your home.nix.
|
||
modules = [
|
||
./home.nix
|
||
];
|
||
|
||
# Optionally use extraSpecialArgs
|
||
# to pass through arguments to home.nix
|
||
};
|
||
};
|
||
}
|
||
----
|
||
+
|
||
[NOTE]
|
||
====
|
||
* The Home Manager library is exported by the flake under `lib.hm`.
|
||
|
||
* You can use the above `flake.nix` as a template in `~/.config/home-manager` by
|
||
+
|
||
[source,console]
|
||
$ nix flake new ~/.config/home-manager -t github:nix-community/home-manager
|
||
====
|
||
|
||
2. Install Home Manager and apply the configuration by
|
||
+
|
||
[source,console]
|
||
$ nix run <flake-uri>#homeConfigurations.jdoe.activationPackage
|
||
+
|
||
Substitute `<flake-uri>` with the flake URI of the configuration flake.
|
||
If `flake.nix` resides in `~/.config/home-manager`,
|
||
`<flake-uri>` may be `~/.config/home-manager`
|
||
as a Git tree or `path:~/.config/home-manager` if not.
|
||
|
||
3. Since the release `21.05`,
|
||
building a flake-based configuration is as simple as
|
||
+
|
||
[source,console]
|
||
$ home-manager switch --flake '<flake-uri>#jdoe'
|
||
+
|
||
once home-manager is installed.
|
||
+
|
||
Here, `jdoe` is a configuration specified in the flake file,
|
||
and `<flake-uri>#jdoe` will be expanded to
|
||
`<flake-uri>#homeConfigurations.jdoe.activationPackage`
|
||
and be built by Nix.
|
||
|
||
[NOTE]
|
||
====
|
||
The flake inputs are not upgraded automatically when switching.
|
||
The analogy to the command `home-manager --update ...` is `nix flake update`.
|
||
|
||
If updating more than one input is undesirable,
|
||
the command `nix flake lock --update-input <input-name>` can be used.
|
||
|
||
You can also pass flake-related options
|
||
such as `--recreate-lock-file` or `--update-input [input]`
|
||
to `home-manager` when building/switching,
|
||
and these options will be forwarded to `nix build`.
|
||
See the {nixos-wiki-flakes}[NixOS Wiki page] for detail.
|
||
====
|
||
|
||
[[sec-flakes-nixos-module]]
|
||
=== NixOS module
|
||
|
||
To use Home Manager as a NixOS module,
|
||
a bare-minimum `flake.nix` would be as follows:
|
||
|
||
[source,nix]
|
||
----
|
||
{
|
||
description = "NixOS configuration";
|
||
|
||
inputs = {
|
||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||
home-manager.url = "github:nix-community/home-manager";
|
||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||
};
|
||
|
||
outputs = inputs@{ nixpkgs, home-manager, ... }: {
|
||
nixosConfigurations = {
|
||
hostname = nixpkgs.lib.nixosSystem {
|
||
system = "x86_64-linux";
|
||
modules = [
|
||
./configuration.nix
|
||
home-manager.nixosModules.home-manager
|
||
{
|
||
home-manager.useGlobalPkgs = true;
|
||
home-manager.useUserPackages = true;
|
||
home-manager.users.jdoe = import ./home.nix;
|
||
|
||
# Optionally, use home-manager.extraSpecialArgs to pass
|
||
# arguments to home.nix
|
||
}
|
||
];
|
||
};
|
||
};
|
||
};
|
||
}
|
||
----
|
||
|
||
The Home Manager configuration is then part of the NixOS configuration
|
||
and is automatically rebuilt with the system when using the appropriate command
|
||
for the system, such as `nixos-rebuild switch --flake <flake-uri>`.
|
||
|
||
You can use the above `flake.nix` as a template in `/etc/nixos` by
|
||
|
||
[source,console]
|
||
$ nix flake new /etc/nixos -t github:nix-community/home-manager#nixos
|
||
|
||
[[sec-flakes-nix-darwin-module]]
|
||
=== nix-darwin module
|
||
|
||
The flake-based setup of the Home Manager nix-darwin module
|
||
is similar to that of NixOS. The `flake.nix` would be:
|
||
|
||
[source,nix]
|
||
----
|
||
{
|
||
description = "Darwin configuration";
|
||
|
||
inputs = {
|
||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||
darwin.url = "github:lnl7/nix-darwin";
|
||
darwin.inputs.nixpkgs.follows = "nixpkgs";
|
||
home-manager.url = "github:nix-community/home-manager";
|
||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||
};
|
||
|
||
outputs = inputs@{ nixpkgs, home-manager, darwin, ... }: {
|
||
darwinConfigurations = {
|
||
hostname = darwin.lib.darwinSystem {
|
||
system = "x86_64-darwin";
|
||
modules = [
|
||
./configuration.nix
|
||
home-manager.darwinModules.home-manager
|
||
{
|
||
home-manager.useGlobalPkgs = true;
|
||
home-manager.useUserPackages = true;
|
||
home-manager.users.jdoe = import ./home.nix;
|
||
|
||
# Optionally, use home-manager.extraSpecialArgs to pass
|
||
# arguments to home.nix
|
||
}
|
||
];
|
||
};
|
||
};
|
||
};
|
||
}
|
||
----
|
||
|
||
and it is also rebuilt with the nix-darwin generations.
|
||
The rebuild command here may be `darwin-rebuild switch --flake <flake-uri>`.
|
||
|
||
You can use the above `flake.nix` as a template in `~/.config/darwin` by
|
||
|
||
[source,console]
|
||
$ nix flake new ~/.config/darwin -t github:nix-community/home-manager#nix-darwin
|