356 lines
11 KiB
Plaintext
356 lines
11 KiB
Plaintext
[[ch-installation]]
|
||
== Installing Home Manager
|
||
|
||
:nix-darwin: https://github.com/LnL7/nix-darwin/
|
||
:nixos-wiki-flakes: https://nixos.wiki/wiki/Flakes
|
||
|
||
Home Manager can be used in three primary 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-install-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-install-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-install-nix-darwin-module>>
|
||
for a description of this setup.
|
||
|
||
[NOTE]
|
||
In this chapter we describe how to install Home Manager in the
|
||
standard way using channels. If you prefer to use
|
||
{nixos-wiki-flakes}[Nix Flakes] then please see the instructions in
|
||
<<ch-nix-flakes>>.
|
||
|
||
[[sec-install-standalone]]
|
||
=== Standalone installation
|
||
|
||
:nix-allowed-users: https://nixos.org/nix/manual/#conf-allowed-users
|
||
:nixos-allowed-users: https://nixos.org/manual/nixos/stable/options.html#opt-nix.settings.allowed-users
|
||
:bash: https://www.gnu.org/software/bash/
|
||
:zsh: http://zsh.sourceforge.net/
|
||
:fish: https://fishshell.com
|
||
:plugin-foreign-env: https://github.com/oh-my-fish/plugin-foreign-env
|
||
:babelfish: https://github.com/bouk/babelfish
|
||
|
||
1. Make sure you have a working Nix installation. Specifically, make
|
||
sure that your user is able to build and install Nix packages. For
|
||
example, you should be able to successfully run a command like
|
||
`nix-instantiate '<nixpkgs>' -A hello` without having to switch to the
|
||
root user. For a multi-user install of Nix this means that your user
|
||
must be covered by the {nix-allowed-users}[`allowed-users`] Nix
|
||
option. On NixOS you can control this option using the
|
||
{nixos-allowed-users}[`nix.settings.allowed-users`] system option.
|
||
|
||
2. Add the appropriate Home Manager channel. If you are following
|
||
Nixpkgs master or an unstable channel you can run
|
||
+
|
||
[source,console]
|
||
----
|
||
$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
|
||
$ nix-channel --update
|
||
----
|
||
+
|
||
and if you follow a Nixpkgs version 23.05 channel you can run
|
||
+
|
||
[source,console]
|
||
----
|
||
$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager
|
||
$ nix-channel --update
|
||
----
|
||
|
||
3. Run the Home Manager installation command and create the first Home
|
||
Manager generation:
|
||
+
|
||
[source,console]
|
||
$ nix-shell '<home-manager>' -A install
|
||
+
|
||
Once finished, Home Manager should be active and available in your
|
||
user environment.
|
||
|
||
4. If you do not plan on having Home Manager manage your shell
|
||
configuration then you must source the
|
||
+
|
||
[source,bash]
|
||
$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh
|
||
+
|
||
file in your shell configuration. Alternatively source
|
||
+
|
||
[source,bash]
|
||
/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh
|
||
+
|
||
when managing home configuration together with system configuration.
|
||
+
|
||
This file can be sourced directly by POSIX.2-like shells such as
|
||
{bash}[Bash] or {zsh}[Z shell]. {fish}[Fish] users can use utilities
|
||
such as {plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
|
||
+
|
||
For example, if you use Bash then add
|
||
+
|
||
[source,bash]
|
||
----
|
||
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||
----
|
||
+
|
||
to your `~/.profile` file.
|
||
|
||
If instead of using channels you want to run Home Manager from a Git
|
||
checkout of the repository then you can use the
|
||
<<opt-programs.home-manager.path>> option to specify the absolute path
|
||
to the repository.
|
||
|
||
Once installed you can see <<ch-usage>> for a more detailed
|
||
description of Home Manager and how to use it.
|
||
|
||
[[sec-install-nixos-module]]
|
||
=== NixOS module
|
||
|
||
Home Manager provides a NixOS module that allows you to prepare user
|
||
environments directly from the system configuration file, which often
|
||
is more convenient than using the `home-manager` tool. It also opens
|
||
up additional possibilities, for example, to automatically configure
|
||
user environments in NixOS declarative containers or on systems
|
||
deployed through NixOps.
|
||
|
||
To make the NixOS module available for use you must `import` it into
|
||
your system configuration. This is most conveniently done by adding a
|
||
Home Manager channel to the root user. For example, if you are
|
||
following Nixpkgs master or an unstable channel, you can run
|
||
|
||
[source,console]
|
||
----
|
||
$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
|
||
$ sudo nix-channel --update
|
||
----
|
||
|
||
and if you follow a Nixpkgs version 23.05 channel, you can run
|
||
|
||
[source,console]
|
||
----
|
||
$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager
|
||
$ sudo nix-channel --update
|
||
----
|
||
|
||
It is then possible to add
|
||
|
||
[source,nix]
|
||
imports = [ <home-manager/nixos> ];
|
||
|
||
to your system `configuration.nix` file, which will introduce a new
|
||
NixOS option called `home-manager.users` whose type is an attribute
|
||
set that maps user names to Home Manager configurations.
|
||
|
||
For example, a NixOS configuration may include the lines
|
||
|
||
[source,nix]
|
||
----
|
||
users.users.eve.isNormalUser = true;
|
||
home-manager.users.eve = { pkgs, ... }: {
|
||
home.packages = [ pkgs.atool pkgs.httpie ];
|
||
programs.bash.enable = true;
|
||
|
||
# The state version is required and should stay at the version you
|
||
# originally installed.
|
||
home.stateVersion = "23.05";
|
||
};
|
||
----
|
||
|
||
and after a `sudo nixos-rebuild switch` the user eve's environment should
|
||
include a basic Bash configuration and the packages atool and httpie.
|
||
|
||
[NOTE]
|
||
====
|
||
If `nixos-rebuild switch` does not result in the environment you expect,
|
||
you can take a look at the output of the Home Manager activation script output using
|
||
|
||
[source,console]
|
||
$ systemctl status "home-manager-$USER.service"
|
||
====
|
||
|
||
If you do not plan on having Home Manager manage your shell
|
||
configuration then you must add either
|
||
|
||
[source,bash]
|
||
----
|
||
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||
----
|
||
|
||
or
|
||
|
||
[source,bash]
|
||
----
|
||
. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
|
||
----
|
||
|
||
to your shell configuration, depending on whether
|
||
<<nixos-opt-home-manager.useUserPackages>> is enabled. This file can
|
||
be sourced directly by POSIX.2-like shells such as {bash}[Bash] or
|
||
{zsh}[Z shell]. {fish}[Fish] users can use utilities such as
|
||
{plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
|
||
|
||
[NOTE]
|
||
====
|
||
By default packages will be installed to `$HOME/.nix-profile` but they
|
||
can be installed to `/etc/profiles` if
|
||
|
||
[source,nix]
|
||
home-manager.useUserPackages = true;
|
||
|
||
is added to the system configuration. This is necessary if, for
|
||
example, you wish to use `nixos-rebuild build-vm`. This option may
|
||
become the default value in the future.
|
||
====
|
||
|
||
[NOTE]
|
||
====
|
||
By default, Home Manager uses a private `pkgs` instance that is
|
||
configured via the `home-manager.users.<name>.nixpkgs` options. To
|
||
instead use the global `pkgs` that is configured via the system level
|
||
`nixpkgs` options, set
|
||
|
||
[source,nix]
|
||
home-manager.useGlobalPkgs = true;
|
||
|
||
This saves an extra Nixpkgs evaluation, adds consistency, and removes
|
||
the dependency on `NIX_PATH`, which is otherwise used for importing
|
||
Nixpkgs.
|
||
====
|
||
|
||
[NOTE]
|
||
====
|
||
Home Manager will pass `osConfig` as a module argument to any modules
|
||
you create. This contains the system's NixOS configuration.
|
||
|
||
[source,nix]
|
||
{ lib, pkgs, osConfig, ... }:
|
||
====
|
||
|
||
Once installed you can see <<ch-usage>> for a more detailed
|
||
description of Home Manager and how to use it.
|
||
|
||
[[sec-install-nix-darwin-module]]
|
||
=== nix-darwin module
|
||
|
||
Home Manager provides a module that allows you to prepare user
|
||
environments directly from the {nix-darwin}[nix-darwin] configuration
|
||
file, which often is more convenient than using the `home-manager`
|
||
tool.
|
||
|
||
To make the NixOS module available for use you must `import` it into
|
||
your system configuration. This is most conveniently done by adding a
|
||
Home Manager channel. For example, if you are following Nixpkgs master
|
||
or an unstable channel, you can run
|
||
|
||
[source,console]
|
||
----
|
||
$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
|
||
$ nix-channel --update
|
||
----
|
||
|
||
and if you follow a Nixpkgs version 23.05 channel, you can run
|
||
|
||
[source,console]
|
||
----
|
||
$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager
|
||
$ nix-channel --update
|
||
----
|
||
|
||
It is then possible to add
|
||
|
||
[source,nix]
|
||
imports = [ <home-manager/nix-darwin> ];
|
||
|
||
to your nix-darwin `configuration.nix` file, which will introduce a
|
||
new NixOS option called `home-manager` whose type is an attribute set
|
||
that maps user names to Home Manager configurations.
|
||
|
||
For example, a nix-darwin configuration may include the lines
|
||
|
||
[source,nix]
|
||
----
|
||
users.users.eve = {
|
||
name = "eve";
|
||
home = "/Users/eve";
|
||
}
|
||
home-manager.users.eve = { pkgs, ... }: {
|
||
home.packages = [ pkgs.atool pkgs.httpie ];
|
||
programs.bash.enable = true;
|
||
|
||
# The state version is required and should stay at the version you
|
||
# originally installed.
|
||
home.stateVersion = "23.05";
|
||
};
|
||
----
|
||
|
||
and after a `darwin-rebuild switch` the user eve's environment
|
||
should include a basic Bash configuration and the packages atool and
|
||
httpie.
|
||
|
||
If you do not plan on having Home Manager manage your shell
|
||
configuration then you must add either
|
||
|
||
[source,bash]
|
||
----
|
||
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||
----
|
||
|
||
or
|
||
|
||
[source,bash]
|
||
----
|
||
. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
|
||
----
|
||
|
||
to your shell configuration, depending on whether
|
||
<<nix-darwin-opt-home-manager.useUserPackages>> is enabled. This file
|
||
can be sourced directly by POSIX.2-like shells such as {bash}[Bash] or
|
||
{zsh}[Z shell]. {fish}[Fish] users can use utilities such as
|
||
{plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
|
||
|
||
[NOTE]
|
||
====
|
||
By default user packages will not be ignored in favor of
|
||
`environment.systemPackages`, but they will be installed to
|
||
`/etc/profiles/per-user/$USERNAME` if
|
||
|
||
[source,nix]
|
||
home-manager.useUserPackages = true;
|
||
|
||
is added to the nix-darwin configuration. This option may become the
|
||
default value in the future.
|
||
====
|
||
|
||
[NOTE]
|
||
====
|
||
By default, Home Manager uses a private `pkgs` instance that is
|
||
configured via the `home-manager.users.<name>.nixpkgs` options. To
|
||
instead use the global `pkgs` that is configured via the system level
|
||
`nixpkgs` options, set
|
||
|
||
[source,nix]
|
||
home-manager.useGlobalPkgs = true;
|
||
|
||
This saves an extra Nixpkgs evaluation, adds consistency, and removes
|
||
the dependency on `NIX_PATH`, which is otherwise used for importing
|
||
Nixpkgs.
|
||
====
|
||
|
||
[NOTE]
|
||
====
|
||
Home Manager will pass `osConfig` as a module argument to any modules
|
||
you create. This contains the system's nix-darwin configuration.
|
||
|
||
[source,nix]
|
||
{ lib, pkgs, osConfig, ... }:
|
||
====
|
||
|
||
Once installed you can see <<ch-usage>> for a more detailed
|
||
description of Home Manager and how to use it.
|