<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refmeta>
<refentrytitle><command>home-manager</command>
</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="source">Home Manager</refmiscinfo>
</refmeta>
<refnamediv>
<refname><command>home-manager</command>
</refname><refpurpose>reconfigure a user environment</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>home-manager</command> <group choice="req">
<arg choice="plain">
build
</arg>
<arg choice="plain">
instantiate
</arg>
<arg choice="plain">
edit
</arg>
<arg choice="plain">
expire-generations <replaceable>timestamp</replaceable>
</arg>
<arg choice="plain">
generations
</arg>
<arg choice="plain">
help
</arg>
<arg choice="plain">
news
</arg>
<arg choice="plain">
packages
</arg>
<arg choice="plain">
remove-generations <replaceable>ID …</replaceable>
</arg>
<arg choice="plain">
switch
</arg>
<arg choice="plain">
uninstall
</arg>
</group>
<sbr />
<arg>
-A <replaceable>attrPath</replaceable>
</arg>
<arg>
-I <replaceable>path</replaceable>
</arg>
<arg>
-b <replaceable>ext</replaceable>
</arg>
<arg>
<group choice="req">
<arg choice="plain">
-f
</arg>
<arg choice="plain">
--file
</arg>
</group> <replaceable>path</replaceable>
</arg>
<arg>
<group choice="req">
<arg choice="plain">
-h
</arg>
<arg choice="plain">
--help
</arg>
</group>
</arg>
<arg>
<group choice="req">
<arg choice="plain">
-n
</arg>
<arg choice="plain">
--dry-run
</arg>
</group>
</arg>
<arg>
--option <replaceable>name</replaceable> <replaceable>value</replaceable>
</arg>
<arg>
--cores <replaceable>number</replaceable>
</arg>
<arg>
--max-jobs <replaceable>number</replaceable>
</arg>
<arg>
--keep-failed
</arg>
<arg>
--keep-going
</arg>
<arg>
--show-trace
</arg>
<arg>
--(no-)substitute
</arg>
<arg>
<group choice="req">
<arg choice="plain">
-v
</arg>
<arg choice="plain">
--verbose
</arg>
</group>
</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
This command updates the user environment so that it corresponds to the
configuration specified in <filename>~/.config/nixpkgs/home.nix</filename>.
</para>
<para>
All operations using this tool expects a sub-command that indicates the
operation to perform. It must be one of
<variablelist>
<varlistentry>
<term>
<option>build</option>
</term>
<listitem>
<para>
Build configuration into a <filename>result</filename> directory.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>instantiate</option>
</term>
<listitem>
<para>
Instantiate the configuration and print the resulting derivation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>edit</option>
</term>
<listitem>
<para>
Open the home configuration using the editor indicated by
<envar>EDITOR</envar>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>expire-generations <replaceable>timestamp</replaceable></option>
</term>
<listitem>
<para>
Remove generations older than <replaceable>timestamp</replaceable> where
<replaceable>timestamp</replaceable> is interpreted as in the
<option>-d</option> argument of the <citerefentry>
<refentrytitle>date</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> tool. For example <literal>-30
days</literal> or <literal>2018-01-01</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>generations</option>
</term>
<listitem>
<para>
List all home environment generations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>help</option>
</term>
<listitem>
<para>
Print tool help.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>news</option>
</term>
<listitem>
<para>
Show news entries in a pager.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>packages</option>
</term>
<listitem>
<para>
List all packages installed in <varname>home-manager-path</varname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>remove-generations <replaceable>ID …</replaceable></option>
</term>
<listitem>
<para>
Remove indicated generations. Use the <option>generations</option>
sub-command to find suitable generation numbers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>switch</option>
</term>
<listitem>
<para>
Build and activate the configuration.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>uninstall</option>
</term>
<listitem>
<para>
Remove Home Manager from the user environment. This will
<itemizedlist>
<listitem>
<para>
remove all managed files from the home directory,
</para>
</listitem>
<listitem>
<para>
remove packages installed through Home Manager from the user profile,
and
</para>
</listitem>
<listitem>
<para>
optionally remove all Home Manager generations and make them
available for immediate garbage collection.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsection>
<refsection>
<title>Options</title>
<para>
The tool accepts the options
</para>
<variablelist>
<varlistentry>
<term>
<option>-A <replaceable>attrPath</replaceable></option>
</term>
<listitem>
<para>
Optional attribute that selects a configuration expression in the
configuration file. That is, if <filename>home.nix</filename> contains
<programlisting language="nix">
{
joe-at-work = {pkgs, ...}: { home.packages = [ pkgs.fortune ]; };
joe-at-home = {pkgs, ...}: { home.packages = [ pkgs.cowsay ]; };
}
</programlisting>
then the command <command>home-manager switch -A joe-at-work</command>
will activate the profile containing the fortune program.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-I <replaceable>path</replaceable></option>
</term>
<listitem>
<para>
Add a path to the Nix expression search path. For example, to build a
Home Manager profile using a specific Nixpkgs run <command>home-manager
-I nixpkgs=/absolute/path/to/nixpkgs build</command>. By default
<literal><nixpkgs></literal> is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-b <replaceable>extension</replaceable></option>
</term>
<listitem>
<para>
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,
<screen>
<prompt>$</prompt> <userinput>home-manager -b bck switch</userinput>
</screen>
will cause a colliding file <filename>~/.config/foo.conf</filename> to be
moved to <filename>~/.config/foo.conf.bck</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-f <replaceable>path</replaceable></option>
</term>
<term>
<option>--file <replaceable>path</replaceable></option>
</term>
<listitem>
<para>
Indicates the path to the Home Manager configuration file. If not given,
<filename>~/.config/nixpkgs/home.nix</filename> is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-h</option>
</term>
<term>
<option>--help</option>
</term>
<listitem>
<para>
Prints usage information for the <command>home-manager</command> tool.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-n</option>
</term>
<term>
<option>--dry-run</option>
</term>
<listitem>
<para>
Perform a dry-run of the given operation, only prints what actions would
be taken.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--option <replaceable>name</replaceable> <replaceable>value</replaceable></option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix-build</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--cores <replaceable>number</replaceable></option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix-build</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--max-jobs <replaceable>number</replaceable></option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix-build</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--keep-failed</option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix-build</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--keep-going</option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix-build</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--show-trace</option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix-build</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--(no-)substitute</option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix-build</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-v</option>
</term>
<term>
<option>--verbose</option>
</term>
<listitem>
<para>
Activates verbose output.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection>
<title>Files</title>
<variablelist>
<varlistentry>
<term>
<filename>~/.local/share/home-manager/news-read-ids</filename>
</term>
<listitem>
<para>
Identifiers of news items that have been shown. Can be deleted to reset
the read news indicator.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection>
<title>Bugs</title>
<para>
Please report any bugs on the
<link
xlink:href="https://github.com/rycee/home-manager/issues">project
issue tracker</link>.
</para>
</refsection>
<refsection>
<title>See also</title>
<para>
<citerefentry>
<refentrytitle>home-configuration.nix</refentrytitle>
<manvolnum>5</manvolnum> </citerefentry>
</para>
</refsection>
</refentry>
