home-manager/docs/man-home-manager.xml

<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">
    init <arg>--switch</arg> <arg><replaceable>dir</replaceable></arg>
   </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">
    option <replaceable>option.name</replaceable>
   </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>
    --flake <replaceable>flake-uri</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>
    --version
   </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>
     <group choice="req">
       <arg choice="plain">
         -j
       </arg>

       <arg choice="plain">
         --max-jobs
       </arg>
     </group>
     <replaceable>number</replaceable>
   </arg>

   <arg>
    --debug
   </arg>

   <arg>
    --impure
   </arg>

   <arg>
    --keep-failed
   </arg>

   <arg>
    --keep-going
   </arg>

   <arg>
    <group choice="req">
     <arg choice="plain">
      -L
     </arg>

     <arg choice="plain">
      --print-build-logs
     </arg>
    </group>
   </arg>

   <arg>
    --show-trace
   </arg>

   <arg>
    --(no-)substitute
   </arg>

   <arg>
    --no-out-link
   </arg>

   <arg>
    --refresh
   </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>$XDG_CONFIG_HOME/home-manager/home.nix</filename> or
   <filename>$XDG_CONFIG_HOME/home-manager/flake.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>init</option> [<option>--switch</option>] [<replaceable>dir</replaceable>]
      </term>
      <listitem>
        <simpara>
          Generates an initial <filename>home.nix</filename> file for the
          current user. If Nix flakes are enabled, then this command also
          generates a <filename>flake.nix</filename> file.
        </simpara>
        <simpara>
          If a path <replaceable>dir</replaceable> is given then the
          configuration will be generated in that directory. Otherwise, the
          configuration will be generated in
          <filename>~/.config/home-manager</filename>. The output directory will
          be created if it does not exist.
        </simpara>
        <simpara>
          If the <option>--switch</option> option is given, then the generated
          configuration is activated.
        </simpara>
        <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 <option>init</option> command with <option>--switch</option>
          enabled to activate the configuration.
        </simpara>
      </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>option <replaceable>option.name</replaceable></option>
     </term>
     <listitem>
      <para>
       Inspect the given option name in the home configuration, like <citerefentry>
       <refentrytitle>nixos-option</refentrytitle>
       <manvolnum>8</manvolnum> </citerefentry>.
      </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>
          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>&lt;nixpkgs&gt;</literal> is used.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--flake <replaceable>flake-uri[#name]</replaceable></option>
    </term>
    <listitem>
     <para>
      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.
     </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>$XDG_CONFIG_HOME/home-manager/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>--version</option>
    </term>
    <listitem>
     <para>
      Prints the version number of 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>-j <replaceable>number</replaceable></option>
    </term>
    <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>--debug</option>
    </term>
    <listitem>
     <para>
      Passed on to <citerefentry>
      <refentrytitle>nix-build</refentrytitle>
      <manvolnum>1</manvolnum> </citerefentry>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--impure</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>-L</option>
    </term>
    <term>
     <option>--print-build-logs</option>
    </term>
    <listitem>
     <para>
      Passed on to <citerefentry>
      <refentrytitle>nix build</refentrytitle>
      </citerefentry>
      when building from a flake.
     </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>--no-out-link</option>
    </term>
    <listitem>
     <para>
      Passed on to <citerefentry>
      <refentrytitle>nix-build</refentrytitle>
      <manvolnum>1</manvolnum> </citerefentry>
      when running <command>home-manager build</command>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--refresh</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>$XDG_DATA_HOME/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/nix-community/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>