home-manager — reconfigure a user environment
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
}
]
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.
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.