2020-10-19 21:06:22 +02:00
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2023-03-01 22:49:01 +01:00
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> < html xmlns = "http://www.w3.org/1999/xhtml" > < head > < meta name = "viewport" content = "width=device-width, initial-scale=1.0" > < meta http-equiv = "Content-Type" content = "text/html; charset=UTF-8" / > < title > Appendix < / title > < link rel = "stylesheet" type = "text/css" href = "style.css" / > < script src = "highlight.min.js" type = "text/javascript" > < / script > < script src = "highlight.load.js" type = "text/javascript" > < / script > < meta name = "generator" content = "DocBook XSL Stylesheets V1.79.2" / > < link rel = "home" href = "index.html" title = "Home Manager Manual" / > < link rel = "up" href = "index.html" title = "Home Manager Manual" / > < link rel = "prev" href = "nix-darwin-options.html" title = "Appendix / > < link rel = "next" href = "release-notes.html" title = "Appendix / > < / head > < body > < div class = "navheader" > < table width = "100%" summary = "Navigation header" > < tr > < th colspan = "3" align = "center" > Appendix < / th > < / tr > < tr > < td width = "20%" align = "left" > < a accesskey = "p" href = "nix-darwin-options.html" > Prev< / a > < / td > < th width = "60%" align = "center" > < / th > < td width = "20%" align = "right" > < a accesskey = "n" href = "release-notes.html" > Next< / a > < / td > < / tr > < / table > < hr / > < / div > < div class = "appendix" > < div class = "titlepage" > < div > < div > < h1 class = "title" > < a id = "ch-tools" > < / a > Appendix < / h1 > < / div > < / div > < / div > < div class = "toc" > < dl class = "toc" > < dt > < span class = "refentrytitle" > < a href = "tools.html#id-1.13.2" > < span class = "command" > < strong > home-manager< / strong > < / span >
< / a > < / span > < span class = "refpurpose" > — reconfigure a user environment< / span > < / dt > < / dl > < / div > < div class = "refentry" > < a id = "id-1.13.2" > < / a > < div class = "titlepage" > < / div > < div class = "refnamediv" > < h2 > Name< / h2 > < p > < span class = "command" > < strong > home-manager< / strong > < / span >
2020-10-19 21:06:22 +02:00
— reconfigure a user environment< / p > < / div > < div class = "refsynopsisdiv" > < h2 > Synopsis< / h2 > < div class = "cmdsynopsis" > < p > < code class = "command" > home-manager< / code > {
build
|
2023-03-15 23:03:42 +01:00
init [--switch] [< em class = "replaceable" > < code > dir< / code > < / em > ]
|
2020-10-19 21:06:22 +02:00
instantiate
|
edit
|
expire-generations < em class = "replaceable" > < code > timestamp< / code > < / em >
|
generations
|
help
|
news
|
2021-06-16 00:10:33 +02:00
option < em class = "replaceable" > < code > option.name< / code > < / em >
|
2020-10-19 21:06:22 +02:00
packages
|
remove-generations < em class = "replaceable" > < code > ID …< / code > < / em >
|
switch
|
uninstall
}< br / > [
-A < em class = "replaceable" > < code > attrPath< / code > < / em >
] [
-I < em class = "replaceable" > < code > path< / code > < / em >
2021-04-07 19:18:30 +02:00
] [
--flake < em class = "replaceable" > < code > flake-uri< / code > < / em >
2020-10-19 21:06:22 +02:00
] [
-b < em class = "replaceable" > < code > ext< / code > < / em >
] [
{
-f
|
--file
} < em class = "replaceable" > < code > path< / code > < / em >
] [
{
-h
|
--help
}
2022-01-02 08:50:03 +01:00
] [
--version
2020-10-19 21:06:22 +02:00
] [
{
-n
|
--dry-run
}
] [
--option < em class = "replaceable" > < code > name< / code > < / em > < em class = "replaceable" > < code > value< / code > < / em >
] [
--cores < em class = "replaceable" > < code > number< / code > < / em >
] [
2020-11-13 23:58:40 +01:00
{
-j
|
--max-jobs
}
< em class = "replaceable" > < code > number< / code > < / em >
2021-06-06 00:11:56 +02:00
] [
--debug
2021-08-19 00:15:44 +02:00
] [
--impure
2020-10-19 21:06:22 +02:00
] [
--keep-failed
] [
--keep-going
2022-12-25 12:35:56 +01:00
] [
{
-L
|
--print-build-logs
}
2020-10-19 21:06:22 +02:00
] [
--show-trace
] [
--(no-)substitute
2021-07-29 16:03:04 +02:00
] [
--no-out-link
2023-02-05 11:14:56 +01:00
] [
--refresh
2020-10-19 21:06:22 +02:00
] [
{
-v
|
--verbose
}
2023-03-01 22:49:01 +01:00
]< / p > < / div > < / div > < div class = "refsection" > < a id = "id-1.13.2.4" > < / a > < h2 > Description< / h2 > < p >
2020-10-19 21:06:22 +02:00
This command updates the user environment so that it corresponds to the
2023-03-14 23:12:30 +01:00
configuration specified in
< code class = "filename" > $XDG_CONFIG_HOME/home-manager/home.nix< / code > or
< code class = "filename" > $XDG_CONFIG_HOME/home-manager/flake.nix< / code > .
2020-10-19 21:06:22 +02:00
< / p > < p >
All operations using this tool expects a sub-command that indicates the
operation to perform. It must be one of
< / p > < div class = "variablelist" > < dl class = "variablelist" > < dt > < span class = "term" >
< code class = "option" > build< / code >
< / span > < / dt > < dd > < p >
Build configuration into a < code class = "filename" > result< / code > directory.
< / p > < / dd > < dt > < span class = "term" >
2023-03-15 23:03:42 +01:00
< code class = "option" > init< / code > [< code class = "option" > --switch< / code > ] [< em class = "replaceable" > < code > dir< / code > < / em > ]
< / span > < / dt > < dd > < p class = "simpara" >
Generates an initial < code class = "filename" > home.nix< / code > file for the
current user. If Nix flakes are enabled, then this command also
generates a < code class = "filename" > flake.nix< / code > file.
< / p > < p class = "simpara" >
If a path < em class = "replaceable" > < code > dir< / code > < / em > is given then the
configuration will be generated in that directory. Otherwise, the
configuration will be generated in
< code class = "filename" > ~/.config/home-manager< / code > . The output directory will
be created if it does not exist.
< / p > < p class = "simpara" >
If the < code class = "option" > --switch< / code > option is given, then the generated
configuration is activated.
< / p > < p class = "simpara" >
Note, this command will not overwrite any existing files. It is
therefore safe to initialize a configuration, edit it, and then re-run
the < code class = "option" > init< / code > command with < code class = "option" > --switch< / code >
enabled to activate the configuration.
< / p > < / dd > < dt > < span class = "term" >
2020-10-19 21:06:22 +02:00
< code class = "option" > instantiate< / code >
< / span > < / dt > < dd > < p >
Instantiate the configuration and print the resulting derivation.
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > edit< / code >
< / span > < / dt > < dd > < p >
Open the home configuration using the editor indicated by
< code class = "envar" > EDITOR< / code > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > expire-generations < em class = "replaceable" > < code > timestamp< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
Remove generations older than < em class = "replaceable" > < code > timestamp< / code > < / em > where
< em class = "replaceable" > < code > timestamp< / code > < / em > is interpreted as in the
< code class = "option" > -d< / code > argument of the < span class = "citerefentry" > < span class = "refentrytitle" > date< / span > (1)< / span > tool. For example < code class = "literal" > -30
days< / code > or < code class = "literal" > 2018-01-01< / code > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > generations< / code >
< / span > < / dt > < dd > < p >
List all home environment generations.
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > help< / code >
< / span > < / dt > < dd > < p >
Print tool help.
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > news< / code >
< / span > < / dt > < dd > < p >
Show news entries in a pager.
< / p > < / dd > < dt > < span class = "term" >
2021-06-16 00:10:33 +02:00
< code class = "option" > option < em class = "replaceable" > < code > option.name< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
Inspect the given option name in the home configuration, like < span class = "citerefentry" > < span class = "refentrytitle" > nixos-option< / span > (8)< / span > .
< / p > < / dd > < dt > < span class = "term" >
2020-10-19 21:06:22 +02:00
< code class = "option" > packages< / code >
< / span > < / dt > < dd > < p >
List all packages installed in < code class = "varname" > home-manager-path< / code > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > remove-generations < em class = "replaceable" > < code > ID …< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
Remove indicated generations. Use the < code class = "option" > generations< / code >
sub-command to find suitable generation numbers.
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > switch< / code >
< / span > < / dt > < dd > < p >
Build and activate the configuration.
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > uninstall< / code >
< / span > < / dt > < dd > < p >
Remove Home Manager from the user environment. This will
< / p > < div class = "itemizedlist" > < ul class = "itemizedlist" style = "list-style-type: disc; " > < li class = "listitem" > < p >
remove all managed files from the home directory,
< / p > < / li > < li class = "listitem" > < p >
remove packages installed through Home Manager from the user profile,
and
< / p > < / li > < li class = "listitem" > < p >
2023-03-14 23:12:30 +01:00
remove all Home Manager generations and make them available
for immediate garbage collection.
2020-10-19 21:06:22 +02:00
< / p > < / li > < / ul > < / div > < p >
< / p > < / dd > < / dl > < / div > < p >
2023-03-01 22:49:01 +01:00
< / p > < / div > < div class = "refsection" > < a id = "id-1.13.2.5" > < / a > < h2 > Options< / h2 > < p >
2020-10-19 21:06:22 +02:00
The tool accepts the options
< / p > < div class = "variablelist" > < dl class = "variablelist" > < dt > < span class = "term" >
< code class = "option" > -A < em class = "replaceable" > < code > attrPath< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
Optional attribute that selects a configuration expression in the
configuration file. That is, if < code class = "filename" > home.nix< / code > contains
< / p > < pre class = "programlisting nix" >
{
joe-at-work = {pkgs, ...}: { home.packages = [ pkgs.fortune ]; };
joe-at-home = {pkgs, ...}: { home.packages = [ pkgs.cowsay ]; };
}
< / pre > < p >
then the command < span class = "command" > < strong > home-manager switch -A joe-at-work< / strong > < / span >
will activate the profile containing the fortune program.
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > -I < em class = "replaceable" > < code > path< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
Add a path to the Nix expression search path. For example, to build a
Home Manager profile using a specific Nixpkgs run < span class = "command" > < strong > home-manager
-I nixpkgs=/absolute/path/to/nixpkgs build< / strong > < / span > . By default
< code class = "literal" > < nixpkgs> < / code > is used.
< / p > < / dd > < dt > < span class = "term" >
2021-04-07 19:18:30 +02:00
< code class = "option" > --flake < em class = "replaceable" > < code > flake-uri[#name]< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
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.
< / p > < / dd > < dt > < span class = "term" >
2020-10-19 21:06:22 +02:00
< code class = "option" > -b < em class = "replaceable" > < code > extension< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
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,
< / p > < pre class = "screen" >
< code class = "prompt" > $< / code > < strong class = "userinput" > < code > home-manager -b bck switch< / code > < / strong >
< / pre > < p >
will cause a colliding file < code class = "filename" > ~/.config/foo.conf< / code > to be
moved to < code class = "filename" > ~/.config/foo.conf.bck< / code > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > -f < em class = "replaceable" > < code > path< / code > < / em > < / code >
, < / span > < span class = "term" >
< code class = "option" > --file < em class = "replaceable" > < code > path< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
Indicates the path to the Home Manager configuration file. If not given,
2023-03-14 23:12:30 +01:00
< code class = "filename" > $XDG_CONFIG_HOME/home-manager/home.nix< / code > is used.
2020-10-19 21:06:22 +02:00
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > -h< / code >
, < / span > < span class = "term" >
< code class = "option" > --help< / code >
< / span > < / dt > < dd > < p >
Prints usage information for the < span class = "command" > < strong > home-manager< / strong > < / span > tool.
< / p > < / dd > < dt > < span class = "term" >
2022-01-02 08:50:03 +01:00
< code class = "option" > --version< / code >
< / span > < / dt > < dd > < p >
Prints the version number of the < span class = "command" > < strong > home-manager< / strong > < / span > tool.
< / p > < / dd > < dt > < span class = "term" >
2020-10-19 21:06:22 +02:00
< code class = "option" > -n< / code >
, < / span > < span class = "term" >
< code class = "option" > --dry-run< / code >
< / span > < / dt > < dd > < p >
Perform a dry-run of the given operation, only prints what actions would
be taken.
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > --option < em class = "replaceable" > < code > name< / code > < / em > < em class = "replaceable" > < code > value< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > --cores < em class = "replaceable" > < code > number< / code > < / em > < / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
2020-11-13 23:58:40 +01:00
< code class = "option" > -j < em class = "replaceable" > < code > number< / code > < / em > < / code >
, < / span > < span class = "term" >
2020-10-19 21:06:22 +02:00
< code class = "option" > --max-jobs < em class = "replaceable" > < code > number< / code > < / em > < / code >
2021-06-06 00:11:56 +02:00
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > --debug< / code >
2021-08-19 00:15:44 +02:00
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > --impure< / code >
2020-10-19 21:06:22 +02:00
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > --keep-failed< / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > --keep-going< / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
2022-12-25 12:35:56 +01:00
< code class = "option" > -L< / code >
, < / span > < span class = "term" >
< code class = "option" > --print-build-logs< / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix build< / span > < / span >
when building from a flake.
< / p > < / dd > < dt > < span class = "term" >
2020-10-19 21:06:22 +02:00
< code class = "option" > --show-trace< / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
< code class = "option" > --(no-)substitute< / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span > .
< / p > < / dd > < dt > < span class = "term" >
2021-07-29 16:03:04 +02:00
< code class = "option" > --no-out-link< / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span >
when running < span class = "command" > < strong > home-manager build< / strong > < / span > .
< / p > < / dd > < dt > < span class = "term" >
2023-02-05 11:14:56 +01:00
< code class = "option" > --refresh< / code >
< / span > < / dt > < dd > < p >
Passed on to < span class = "citerefentry" > < span class = "refentrytitle" > nix-build< / span > (1)< / span >
< / p > < / dd > < dt > < span class = "term" >
2020-10-19 21:06:22 +02:00
< code class = "option" > -v< / code >
, < / span > < span class = "term" >
< code class = "option" > --verbose< / code >
< / span > < / dt > < dd > < p >
Activates verbose output.
2023-03-01 22:49:01 +01:00
< / p > < / dd > < / dl > < / div > < / div > < div class = "refsection" > < a id = "id-1.13.2.6" > < / a > < h2 > Files< / h2 > < div class = "variablelist" > < dl class = "variablelist" > < dt > < span class = "term" >
2021-12-11 00:11:16 +01:00
< code class = "filename" > $XDG_DATA_HOME/home-manager/news-read-ids< / code >
2020-10-19 21:06:22 +02:00
< / span > < / dt > < dd > < p >
Identifiers of news items that have been shown. Can be deleted to reset
the read news indicator.
2023-03-01 22:49:01 +01:00
< / p > < / dd > < / dl > < / div > < / div > < div class = "refsection" > < a id = "id-1.13.2.7" > < / a > < h2 > Bugs< / h2 > < p >
2020-10-19 21:06:22 +02:00
Please report any bugs on the
2020-10-19 21:27:00 +02:00
< a class = "link" href = "https://github.com/nix-community/home-manager/issues" target = "_top" > project
2020-10-19 21:06:22 +02:00
issue tracker< / a > .
2023-03-01 22:49:01 +01:00
< / p > < / div > < div class = "refsection" > < a id = "id-1.13.2.8" > < / a > < h2 > See also< / h2 > < p >
2020-10-19 21:06:22 +02:00
< span class = "citerefentry" > < span class = "refentrytitle" > home-configuration.nix< / span > (5)< / span >
2021-01-21 23:50:50 +01:00
< / p > < / div > < / div > < / div > < div class = "navfooter" > < hr / > < table width = "100%" summary = "Navigation footer" > < tr > < td width = "40%" align = "left" > < a accesskey = "p" href = "nix-darwin-options.html" > Prev< / a > < / td > < td width = "20%" align = "center" > < / td > < td width = "40%" align = "right" > < a accesskey = "n" href = "release-notes.html" > Next< / a > < / td > < / tr > < tr > < td width = "40%" align = "left" valign = "top" > Appendix < / td > < td width = "20%" align = "center" > < a accesskey = "h" href = "index.html" > Home< / a > < / td > < td width = "40%" align = "right" valign = "top" > < / td > < / tr > < / table > < / div > < / body > < / html >
