nix-darwin module

Home Manager provides a module that allows you to prepare user environments directly from the nix-darwin configuration file, which often is more convenient than using the home-manager tool.

To make the nix-darwin 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

$ 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 26.05 channel, you can run

$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-26.05.tar.gz home-manager
$ nix-channel --update

It is then possible to add

imports = [ <home-manager/nix-darwin> ];

to your nix-darwin configuration.nix file, which will introduce a home-manager.users option whose type is an attribute set that maps user names to Home Manager configurations.

For example, a nix-darwin configuration may include the lines

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 = "26.05";
};

and after a darwin-rebuild switch the user eve’s environment should include a basic Bash configuration and the packages atool and httpie.

Home Manager activation runs as part of nix-darwin activation for each configured user.

If you do not plan on having Home Manager manage your shell configuration then you must add either

. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"

or

. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"

to your shell configuration, depending on whether home-manager.useUserPackages is enabled. This file can be sourced directly by POSIX.2-like shells such as Bash or Z shell. Fish users can use utilities such as foreign-env or 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

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

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 passes extra module arguments to each home-manager.users.<name> module:

{ lib, pkgs, osConfig, darwinConfig, osClass, modulesPath, ... }:

Here osConfig contains the system’s nix-darwin configuration and darwinConfig is a Darwin-specific alias for the same value. The lib argument is Home Manager’s extended library. You can pass additional module arguments with home-manager.extraSpecialArgs.

Note Use home-manager.sharedModules to add Home Manager modules to every user declared under home-manager.users.

Once installed you can see Using Home Manager for a more detailed description of Home Manager and how to use it.