Appendix D. Tools

home-manager — reconfigure a user environment

Name

home-manager — reconfigure a user environment

Synopsis

home-manager { build | instantiate | edit | expire-generations timestamp | generations | help | news | option option.name | packages | remove-generations ID … | switch | uninstall }
[ -A attrPath ] [ -I path ] [ --flake flake-uri ] [ -b ext ] [ { -f | --file } path ] [ { -h | --help } ] [ --version ] [ { -n | --dry-run } ] [ --option name value ] [ --cores number ] [ { -j | --max-jobs } number ] [ --debug ] [ --impure ] [ --keep-failed ] [ --keep-going ] [ --show-trace ] [ --(no-)substitute ] [ --no-out-link ] [ { -v | --verbose } ]

Description

This command updates the user environment so that it corresponds to the configuration specified in ~/.config/nixpkgs/home.nix or ~/.config/nixpkgs/flake.nix.

All operations using this tool expects a sub-command that indicates the operation to perform. It must be one of

build

Build configuration into a result directory.

instantiate

Instantiate the configuration and print the resulting derivation.

edit

Open the home configuration using the editor indicated by EDITOR.

expire-generations timestamp

Remove generations older than timestamp where timestamp is interpreted as in the -d argument of the date(1) tool. For example -30 days or 2018-01-01.

generations

List all home environment generations.

help

Print tool help.

news

Show news entries in a pager.

option option.name

Inspect the given option name in the home configuration, like nixos-option(8).

packages

List all packages installed in home-manager-path.

remove-generations ID …

Remove indicated generations. Use the generations sub-command to find suitable generation numbers.

switch

Build and activate the configuration.

uninstall

Remove Home Manager from the user environment. This will

  • remove all managed files from the home directory,

  • remove packages installed through Home Manager from the user profile, and

  • optionally remove all Home Manager generations and make them available for immediate garbage collection.

Options

The tool accepts the options

-A attrPath

Optional attribute that selects a configuration expression in the configuration file. That is, if home.nix contains

{
  joe-at-work = {pkgs, ...}: { home.packages = [ pkgs.fortune ]; };
  joe-at-home = {pkgs, ...}: { home.packages = [ pkgs.cowsay ]; };
}

then the command home-manager switch -A joe-at-work will activate the profile containing the fortune program.

-I path

Add a path to the Nix expression search path. For example, to build a Home Manager profile using a specific Nixpkgs run home-manager -I nixpkgs=/absolute/path/to/nixpkgs build. By default <nixpkgs> is used.

--flake flake-uri[#name]

Build Home Manager configuration from the flake, which must contain the output homeConfigurations.name. If no name is specified it will first try username@hostname and then username.

-b extension

Enable automatic resolution of collisions between unmanaged and managed files. The name of the original file will be suffixed by the given extension. For example,

$ home-manager -b bck switch

will cause a colliding file ~/.config/foo.conf to be moved to ~/.config/foo.conf.bck.

-f path , --file path

Indicates the path to the Home Manager configuration file. If not given, $XDG_CONFIG_HOME/nixpkgs/home.nix is used.

-h , --help

Prints usage information for the home-manager tool.

--version

Prints the version number of the home-manager tool.

-n , --dry-run

Perform a dry-run of the given operation, only prints what actions would be taken.

--option name value

Passed on to nix-build(1).

--cores number

Passed on to nix-build(1).

-j number , --max-jobs number

Passed on to nix-build(1).

--debug

Passed on to nix-build(1).

--impure

Passed on to nix-build(1).

--keep-failed

Passed on to nix-build(1).

--keep-going

Passed on to nix-build(1).

--show-trace

Passed on to nix-build(1).

--(no-)substitute

Passed on to nix-build(1).

--no-out-link

Passed on to nix-build(1) when running home-manager build.

-v , --verbose

Activates verbose output.

Files

$XDG_DATA_HOME/home-manager/news-read-ids

Identifiers of news items that have been shown. Can be deleted to reset the read news indicator.

Bugs

Please report any bugs on the project issue tracker.

See also

home-configuration.nix(5)