path: root/doc/manual/nix-env.xml

<refentry>
  <refnamediv>
    <refname>nix-env</refname>
    <refpurpose>manipulate or query Nix user environments</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>nix-env</command>
      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
      <arg>
        <group choice='req'>
          <arg choice='plain'><option>--file</option></arg>
          <arg choice='plain'><option>-f</option></arg>
        </group>
        <replaceable>path</replaceable>
      </arg>
      <arg>
        <group choice='req'>
          <arg choice='plain'><option>--profile</option></arg>
          <arg choice='plain'><option>-p</option></arg>
        </group>
        <replaceable>path</replaceable>
      </arg>
      <arg><option>--preserve-installed</option></arg>
      <arg>
        <arg choice='plain'><option>--system-filter</option></arg>
        <replaceable>system</replaceable>
      </arg>
      <arg><option>--dry-run</option></arg>
      <arg choice='plain'><replaceable>operation</replaceable></arg>
      <arg rep='repeat'><replaceable>options</replaceable></arg>
      <arg rep='repeat'><replaceable>arguments</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>

    <para>
      The command <command>nix-env</command> is used to manipulate Nix
      user environments.  User environments are sets of software
      components available to a user at some point in time.  In other
      words, they are a synthesised view of the programs available in
      the Nix store.  There may be many user environments: different
      users can have different environments, and individual users can
      switch between different environments.
    </para>

<!--    <para>
      Environments are manipulated by operations such as the
      installation and removal of components (hereafter called
      <emphasis>derivations</emphasis>).  These operations are not
      destructive: rather than overwrite the current environment, they
      create a new environment to which we can then atomically
      <emphasis>switch</emphasis> by flipping a symlink.
    </para> -->

    <para>
      <command>nix-env</command> takes exactly one
      <emphasis>operation</emphasis> flag which indicates the
      subcommand to be performed.  These are documented below.
    </para>
    
  </refsection>



  <!--######################################################################-->

  <refsection>
    <title>Common options</title>

    <para>
      This section lists the options that are common to all
      operations.  These options are allowed for every subcommand,
      though they may not always have an effect.
    </para>

    <variablelist>

      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml#xpointer(/nop/*)" />

      <varlistentry>
        <term><option>--file</option> / <option>-f</option></term>
        <listitem>
          <para>
            Specifies the Nix expression (designated below as the
            <emphasis>active Nix expression</emphasis>) used by the
            <option>--install</option>, <option>--upgrade</option>,
            and <option>--query --available</option> operations to
            obtain derivations.  The default is
            <filename>~/.nix-defexpr</filename>.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><option>--profile</option> / <option>-p</option></term>
        <listitem>
          <para>
            Specifies the profile to be used by those operations that
            operate on a profile (designated below as the
            <emphasis>active profile</emphasis>).  A profile is
            sequence of user environments called
            <emphasis>generations</emphasis>, one of which is the
            <emphasis>current generation</emphasis>.  The default
            profile is the target of the symbolic link
            <filename>~/.nix-profile</filename> (see below).
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><option>--dry-run</option></term>
        <listitem>
          <para>
            For the <option>--install</option>,
            <option>--upgrade</option>, <option>--uninstall</option>,
            <option>--switch-generation</option> and
            <option>--rollback</option> operations, this flag will
            cause <command>nix-env</command> to print what
            <emphasis>would</emphasis> be done if this flag had not
            been specified, without actually doing it.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><option>--preserve-installed</option></term>
        <listitem>
          <para>
            By default, when you install a derivation with the
            <option>--install</option> operation, it will replace
            previously installed versions with the same derivation
            name (regardless of the version number).  This option
            causes those previously installed versions to be kept in
            the new generation of the profile.  Note that this will
            generally cause conflicts in the creation of the user
            environment (since multiple versions of a package
            typically contain the same programs).
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><option>--system-filter</option> <replaceable>system</replaceable></term>
        <listitem>
          <para>
            By default, operations such as <option>--query
            --available</option> only include derivations matching the
            current platform.  This option allows you to use
            derivations for the specified platform
            <replaceable>system</replaceable>.  The special value
            <literal>*</literal> causes derivations for any platform
            to be included.
          </para>
        </listitem>
      </varlistentry>
      
    </variablelist>

  </refsection>

  

  <!--######################################################################-->

  <refsection>
    <title>Files</title>

    <variablelist>

      <varlistentry>
        <term><filename>~/.nix-defexpr</filename></term>
        <listitem>
          <para>
            The default Nix expression used by the
            <option>--install</option>, <option>--upgrade</option>,
            and <option>--query --available</option> operations to
            obtain derivations.  It is generally a symbolic link to
            some other location set using the
            <option>--import</option> operation.  The
            <option>--file</option> option may be used to override
            this default.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><filename>~/.nix-profile</filename></term>
        <listitem>
          <para>
            A symbolic link to the user's current profile.  By
            default, this symlink points to
            <filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename>.
            The <envar>PATH</envar> environment variable should
            include <filename>~/.nix-profile/bin</filename> for the
            user environment to be visible to the user.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
        
  </refsection>

  

  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--install</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <group choice='req'>
          <arg choice='plain'><option>--install</option></arg>
          <arg choice='plain'><option>-i</option></arg>
        </group>
        <group choice='opt'>
          <arg choice='plain'><option>--preserve-installed</option></arg>
          <arg choice='plain'><option>-P</option></arg>
        </group>
        <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        The install operation creates a new user environment, based on
        the current generation of the active profile, to which the
        derivations designated by <replaceable>drvnames</replaceable>
        in the active Nix expression are added.
      </para>

      <para>
        Currently installed derivations with a name equal to the name
        of a derivation being added are removed unless the option
        <option>--preserve-installed</option> is specified.
      </para>

    </refsection>

    <refsection>
      <title>Flags</title>

      <variablelist>

        <varlistentry>
          <term><option>--preserve-installed</option> / <option>-P</option></term>
          <listitem>
            <para>
              Do not remove derivations with a name matching one of
              the derivations being installed.  Usually, trying to
              have two versions of the same package installed in the
              same generation of a profile will lead to an error in
              building the generation, due to file name clashes
              between the two versions.  However, this is not the case
              for all packages.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
    </refsection>
            
    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env --install gcc-3.3.2 <lineannotation>(install specific version)</lineannotation>
installing `gcc-3.3.2'
uninstalling `gcc-3.1' <lineannotation>(previously installed version is removed)</lineannotation>

$ nix-env --install gcc <lineannotation>(just pick any version)</lineannotation>

$ nix-env -f ~/foo.nix -i '*' <lineannotation>(install everything in <filename>foo.nix</filename>)</lineannotation></screen>

    </refsection>
    
  </refsection>


  
  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--upgrade</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <group choice='req'>
          <arg choice='plain'><option>--upgrade</option></arg>
          <arg choice='plain'><option>-u</option></arg>
        </group>
        <group choice='opt'>
          <arg choice='plain'><option>--lt</option></arg>
          <arg choice='plain'><option>--leq</option></arg>
          <arg choice='plain'><option>--always</option></arg>
        </group>
        <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        The upgrade operation creates a new user environment, based on
        the current generation of the active profile, in which all
        derivations designated by <replaceable>drvnames</replaceable>
        for which there are newer versions in the active Nix
        expression are replaced by those newer versions.  Matching
        derivations for which there are no newer versions are left
        untouched; this is not an error.  It is also not an error if
        an element of <replaceable>drvnames</replaceable> matches no
        installed derivations.
      </para>

      <para>
        If multiple derivations in the active Nix expression match an
        installed derivation, the one with the highest version is
        selected.
      </para>

    </refsection>
            
    <refsection>
      <title>Flags</title>

      <variablelist>

        <varlistentry>
          <term><option>--lt</option></term>
          <listitem>
            <para>
              Only upgrade a derivation to newer versions.  This is
              the default.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--leq</option></term>
          <listitem>
            <para>
              In addition to upgrading to newer versions, also
              <quote>upgrade</quote> to derivations that have the same
              version.  Version are not a unique identification of a
              derivation, so there may be many derivations that have
              the same version.  This flag may be useful to force
              <quote>synchronisation</quote> between the installed and
              available derivations.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--always</option></term>
          <listitem>
            <para>
              In addition to upgrading to newer versions, also
              <quote>upgrade</quote> to derivations that have the same
              or a lower version.  I.e., derivations may actually be
              downgraded depending on what is available in the active
              Nix expression.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

    </refsection>

    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env --upgrade gcc
upgrading `gcc-3.3.1' to `gcc-3.4'

$ nix-env -u gcc-3.3.2 --always <lineannotation>(switch to a specific version)</lineannotation>
upgrading `gcc-3.4' to `gcc-3.3.2'

$ nix-env --upgrade pan
<lineannotation>(no upgrades available, so nothing happens)</lineannotation>

$ nix-env -u '*' <lineannotation>(try to upgrade everything)</lineannotation>
upgrading `hello-2.1.2' to `hello-2.1.3'
upgrading `mozilla-1.2' to `mozilla-1.4'</screen>        

    </refsection>
    
    <refsection>
      <title>Versions</title>

      <para>
        The upgrade operation determines whether a derivation
        <varname>y</varname> is an upgrade of a derivation
        <varname>x</varname> by looking at their respective
        <literal>name</literal> attributes.  The names (e.g.,
        <literal>gcc-3.3.1</literal> are split into two parts: the
        package name (<literal>gcc</literal>), and the version
        (<literal>3.3.1</literal>).  The version part starts after the
        first dash not following by a letter.  <varname>x</varname> is
        considered an upgrade of <varname>y</varname> if their package
        names match, and the version of <varname>y</varname> is higher
        that that of <varname>x</varname>.
      </para>

      <para>
        The versions are compared by splitting them into contiguous
        components of numbers and letters.  E.g.,
        <literal>3.3.1pre5</literal> is split into <literal>[3, 3, 1,
        "pre", 5]</literal>.  These lists are then compared
        lexicographically (from left to right).  Corresponding
        components <varname>a</varname> and <varname>b</varname> are
        compared as follows.  If they are both numbers, integer
        comparison is used.  If <varname>a</varname> is an empty
        string and <varname>b</varname> is a number,
        <varname>a</varname> is considered less than
        <varname>b</varname>.  The special string component
        <literal>pre</literal> (for <emphasis>pre-release</emphasis>)
        is considered to be less than other components.  String
        components are considered less than number components.
        Otherwise, they are compared lexicographically (i.e., using
        case-sensitive string comparison).
      </para>

      <para>
        This is illustrated by the following examples:

        <screen>
1.0 &lt; 2.3
2.1 &lt; 2.3
2.3 = 2.3
2.5 > 2.3
3.1 > 2.3
2.3.1 > 2.3
2.3.1 > 2.3a
2.3pre1 &lt; 2.3
2.3pre3 &lt; 2.3pre12
2.3a &lt; 2.3c
2.3pre1 &lt; 2.3c
2.3pre1 &lt; 2.3q</screen>
        
      </para>

    </refsection>
            
  </refsection>

  

  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--uninstall</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <group choice='req'>
          <arg choice='plain'><option>--uninstall</option></arg>
          <arg choice='plain'><option>-e</option></arg>
        </group>
        <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        The uninstall operation creates a new user environment, based
        on the current generation of the active profile, from which the
        derivations designated by <replaceable>drvnames</replaceable>
        are removed.
      </para>

    </refsection>
            
    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env --uninstall gcc
$ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>

    </refsection>
    
  </refsection>


  
  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--query</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <group choice='req'>
          <arg choice='plain'><option>--query</option></arg>
          <arg choice='plain'><option>-q</option></arg>
        </group>
        <group choice='opt'>
          <arg choice='plain'><option>--installed</option></arg>
          <arg choice='plain'><option>--available</option></arg>
          <arg choice='plain'><option>-a</option></arg>
        </group>
        <group choice='req'>
          <arg choice='plain'><option>--name</option></arg>
          <arg choice='plain'><option>--expr</option></arg>
          <arg choice='plain'><option>--status</option></arg>
          <arg choice='plain'><option>-s</option></arg>
        </group>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        The query operation displays information about either the
        derivations that are installed in the current generation of
        the active profile (<option>--installed</option>), or the
        derivations that are available for installation in the active
        Nix expression (<option>--available</option>).
      </para>

      <para>
        The derivations are sorted by their <literal>name</literal>
        attributes.
      </para>

    </refsection>

    <refsection>
      <title>Source selection</title>

      <para>
        The following flags specify the set of derivations on which
        the query operates.
      </para>

      <variablelist>

        <varlistentry>
          <term><option>--installed</option></term>
          <listitem>
            <para>
              The query operates on the derivations that are installed
              in the current generation of the active profile.  This
              is the default
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--available</option> / <option>-a</option></term>
          <listitem>
            <para>
              The query operates on the derivations that are available
              in the active Nix expression.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
            
    </refsection>

    <refsection>
      <title>Queries</title>

      <para>
        The following flags specify what information to display about
        the selected derivations.  Only one type of query may be
        specified.
      </para>

      <variablelist>

        <varlistentry>
          <term><option>--name</option></term>
          <listitem>
            <para>
              Prints the <literal>name</literal> attribute of each
              derivation.  This is the default.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--expr</option></term>
          <listitem>
            <para>
              Prints the store expression in the Nix store that
              described the derivation.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--status</option> / <option>-s</option></term>
          <listitem>
            <para>
              Prints the <emphasis>status</emphasis> of each
              derivation, followed by its <literal>name</literal>
              attribute.  The status consists of three characters.
              The first is <literal>I</literal> or
              <literal>-</literal>, indicating whether the derivation
              is currently installed in the current generation of the
              active profile.  This is by definition the case for
              <option>--installed</option>, but not for
              <option>--available</option>.  The second is
              <literal>P</literal> or <literal>-</literal>, indicating
              whether the derivation is present on the system.  This
              indicates whether installation of an available
              derivation will require the derivation to be built.  The
              third is <literal>S</literal> or <literal>-</literal>,
              indicating whether a substitute is available for the
              derivation.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
              
    </refsection>

    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env -q <lineannotation>(show installed derivations)</lineannotation>
MozillaFirebird-0.7
bison-1.875c
docbook-xml-4.2
...

$ nix-env -qa <lineannotation>(show available derivations)</lineannotation>
GConf-2.4.0.1
MPlayer-1.0pre3
MozillaFirebird-0.7
ORBit2-2.8.3
...

$ nix-env -qas <lineannotation>(show status of available derivations)</lineannotation>
-P- GConf-2.4.0.1 <lineannotation>(not installed but present)</lineannotation>
--S MPlayer-1.0pre3 <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation>
--S MozillaFirebird-0.7 <lineannotation>(i.e., this is not the installed Firebird, even though the version is the same!)</lineannotation>
IP- bison-1.875c <lineannotation>(installed and by definition present)</lineannotation>
...

$ nix-env -f ./foo.nix -qa <lineannotation>(show available derivations in the Nix expression <filename>foo.nix</filename>)</lineannotation>
foo-1.2.3</screen>

    </refsection>
    
  </refsection>
  
    

  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--switch-profile</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <group choice='req'>
          <arg choice='plain'><option>--switch-profile</option></arg>
          <arg choice='plain'><option>-S</option></arg>
        </group>
        <arg choice='req'><replaceable>path</replaceable></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        This operation makes <replaceable>path</replaceable> the
        current profile for the user.  That is, the symlink
        <filename>~/.nix-profile</filename> is made to point to
        <replaceable>path</replaceable>.
      </para>

    </refsection>
            
    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env -S ~/my-profile</screen>

    </refsection>
    
  </refsection>


  
  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--list-generations</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <arg choice='req'><option>--list-generations</option></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        This operation print a list of all the currently existing
        generations for the active profile.  These may be switched to
        using the <option>--switch-generation</option> operation.  It
        also prints the creation date of the generation, and indicates
        the current generation.
      </para>

    </refsection>
            
    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env --list-generations
  95   2004-02-06 11:48:24
  96   2004-02-06 11:49:01
  97   2004-02-06 16:22:45
  98   2004-02-06 16:24:33   (current)</screen>

    </refsection>
    
  </refsection>


  
  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--delete-generations</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <arg choice='req'><option>--delete-generations</option></arg>
        <arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        This operation deletes the specified generations of the
        current profile.  The generations can be a list of generation
        numbers, or the special value <literal>old</literal> to delete
        all non-current generations.  Periodically deleting old
        generations is important to make garbage collection effective.
      </para>

    </refsection>
            
    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env --delete-generations 3 4 8

$ nix-env -p other_profile --delete-generations old</screen>

    </refsection>
    
  </refsection>


  
  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--switch-generation</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <group choice='req'>
          <arg choice='plain'><option>--switch-generation</option></arg>
          <arg choice='plain'><option>-G</option></arg>
        </group>
        <arg choice='req'><replaceable>generation</replaceable></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        This operation makes generation number
        <replaceable>generation</replaceable> the current generation
        of the active profile.  That is, if the
        <filename><replaceable>profile</replaceable></filename> is the
        path to the active profile, then the symlink
        <filename><replaceable>profile</replaceable></filename> is
        made to point to
        <filename><replaceable>profile</replaceable>-<replaceable>generation</replaceable>-link</filename>,
        which is in turn a symlink to the actual user environment in
        the Nix store.
      </para>

      <para>
        Switching will fail if the specified generation does not
        exist.
      </para>

    </refsection>
            
    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env -G 42
switching from generation 50 to 42</screen>

    </refsection>
    
  </refsection>


  
  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--rollback</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <arg choice='req'><option>--rollback</option></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        This operation switches to the <quote>previous</quote>
        generation of the active profile, that is, the highest
        numbered generation lower than the current generation, if it
        exists.  It is just a convenience wrapper around
        <option>--list-generations</option> and
        <option>--switch-generation</option>.
      </para>

    </refsection>
            
    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env --rollback
switching from generation 92 to 91

$ nix-env --rolback
error: no generation older than the current (91) exists</screen>

    </refsection>
    
  </refsection>


  
  <!--######################################################################-->

  <refsection>
    <title>Operation <option>--import</option></title>

    <refsection>
      <title>Synopsis</title>
      <cmdsynopsis>
        <command>nix-env</command>
        <group choice='req'>
          <arg choice='plain'><option>--import</option></arg>
          <arg choice='plain'><option>-I</option></arg>
        </group>
        <arg choice='req'><replaceable>path</replaceable></arg>
      </cmdsynopsis>
    </refsection>

    <refsection>
      <title>Description</title>
            
      <para>
        This operation makes <replaceable>path</replaceable> the
        default active Nix expression for the user.  That is, the
        symlink <filename>~/.nix-userenv</filename> is made to point
        to <replaceable>path</replaceable>.
      </para>

    </refsection>
            
    <refsection>
      <title>Examples</title>

      <screen>
$ nix-env -I ~/nixpkgs-0.5/</screen>

    </refsection>
    
  </refsection>


  
</refentry>