path: root/third_party/nix/doc/manual/command-ref/nix-env.xml

<refentry xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      version="5.0"
      xml:id="sec-nix-env">

<refmeta>
  <refentrytitle>nix-env</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
</refmeta>

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

<refsynopsisdiv>
  <cmdsynopsis>
    <command>nix-env</command>
    <xi:include href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <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>
      <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 packages
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><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>Selectors</title>

<para>Several commands, such as <command>nix-env -q</command> and
<command>nix-env -i</command>, take a list of arguments that specify
the packages on which to operate. These are extended regular
expressions that must match the entire name of the package. (For
details on regular expressions, see
<citerefentry><refentrytitle>regex</refentrytitle><manvolnum>7</manvolnum></citerefentry>.)
The match is case-sensitive. The regular expression can optionally be
followed by a dash and a version number; if omitted, any version of
the package will match.  Here are some examples:

<variablelist>

  <varlistentry>
    <term><literal>firefox</literal></term>
    <listitem><para>Matches the package name
    <literal>firefox</literal> and any version.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>firefox-32.0</literal></term>
    <listitem><para>Matches the package name
    <literal>firefox</literal> and version
    <literal>32.0</literal>.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>gtk\\+</literal></term>
    <listitem><para>Matches the package name
    <literal>gtk+</literal>. The <literal>+</literal> character must
    be escaped using a backslash to prevent it from being interpreted
    as a quantifier, and the backslash must be escaped in turn with
    another backslash to ensure that the shell passes it
    on.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>.\*</literal></term>
    <listitem><para>Matches any package name. This is the default for
    most commands.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>'.*zip.*'</literal></term>
    <listitem><para>Matches any package name containing the string
    <literal>zip</literal>. Note the dots: <literal>'*zip*'</literal>
    does not work, because in a regular expression, the character
    <literal>*</literal> is interpreted as a
    quantifier.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>'.*(firefox|chromium).*'</literal></term>
    <listitem><para>Matches any package name containing the strings
    <literal>firefox</literal> or
    <literal>chromium</literal>.</para></listitem>
  </varlistentry>

</variablelist>

</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.  <phrase condition="manual">See
also <xref linkend="sec-common-options" />.</phrase></para>

<variablelist>

  <varlistentry><term><option>--file</option> / <option>-f</option> <replaceable>path</replaceable></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>

    <para>If the argument starts with <literal>http://</literal> or
    <literal>https://</literal>, it is interpreted as the URL of a
    tarball that will be downloaded and unpacked to a temporary
    location. The tarball must include a single top-level directory
    containing at least a file named <filename>default.nix</filename>.</para>

    </listitem>

  </varlistentry>

  <varlistentry><term><option>--profile</option> / <option>-p</option> <replaceable>path</replaceable></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 a sequence of
    user environments called <emphasis>generations</emphasis>, one of
    which is the <emphasis>current
    generation</emphasis>.</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>,
    <option>--delete-generations</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>

    <para><option>--dry-run</option> also prints out which paths will
    be <link linkend="gloss-substitute">substituted</link> (i.e.,
    downloaded) and which paths will be built from source (because no
    substitute is available).</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term>

    <listitem><para>By default, operations such as <option>--query
    --available</option> show derivations matching any platform.  This
    option allows you to use derivations for the specified platform
    <replaceable>system</replaceable>.</para></listitem>

  </varlistentry>

</variablelist>

<variablelist condition="manpage">
  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
</variablelist>

</refsection>



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

<refsection><title>Files</title>

<variablelist>

  <varlistentry><term><filename>~/.nix-defexpr</filename></term>

    <listitem><para>The source for the default Nix
    expressions used by the <option>--install</option>,
    <option>--upgrade</option>, and <option>--query
    --available</option> operations to obtain derivations. The
    <option>--file</option> option may be used to override this
    default.</para>

    <para>If <filename>~/.nix-defexpr</filename> is a file,
    it is loaded as a Nix expression. If the expression
    is a set, it is used as the default Nix expression.
    If the expression is a function, an empty set is passed
    as argument and the return value is used as
    the default Nix expression.</para>

    <para>If <filename>~/.nix-defexpr</filename> is a directory
    containing a <filename>default.nix</filename> file, that file
    is loaded as in the above paragraph.</para>

    <para>If <filename>~/.nix-defexpr</filename> is a directory without
    a <filename>default.nix</filename> file, then its contents
    (both files and subdirectories) are loaded as Nix expressions.
    The expressions are combined into a single set, each expression
    under an attribute with the same name as the original file
    or subdirectory.
    </para>

    <para>For example, if <filename>~/.nix-defexpr</filename> contains
    two files, <filename>foo.nix</filename> and <filename>bar.nix</filename>,
    then the default Nix expression will essentially be

<programlisting>
{
  foo = import ~/.nix-defexpr/foo.nix;
  bar = import ~/.nix-defexpr/bar.nix;
}</programlisting>

    </para>

    <para>The file <filename>manifest.nix</filename> is always ignored.
    Subdirectories without a <filename>default.nix</filename> file
    are traversed recursively in search of more Nix expressions,
    but the names of these intermediate directories are not
    added to the attribute paths of the default Nix expression.</para>

    <para>The command <command>nix-channel</command> places symlinks
    to the downloaded Nix expressions from each subscribed channel in
    this directory.</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 xml:id="rsec-nix-env-install"><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>
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
  <group choice='opt'>
    <arg choice='plain'><option>--preserve-installed</option></arg>
    <arg choice='plain'><option>-P</option></arg>
  </group>
  <group choice='opt'>
    <arg choice='plain'><option>--remove-all</option></arg>
    <arg choice='plain'><option>-r</option></arg>
  </group>
  <arg choice='plain' rep='repeat'><replaceable>args</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 a set of store
paths described by <replaceable>args</replaceable> is added.  The
arguments <replaceable>args</replaceable> map to store paths in a
number of possible ways:

<itemizedlist>

  <listitem><para>By default, <replaceable>args</replaceable> is a set
  of derivation names denoting derivations in the active Nix
  expression.  These are realised, and the resulting output paths are
  installed.  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>

  <para>If there are multiple derivations matching a name in
  <replaceable>args</replaceable> that have the same name (e.g.,
  <literal>gcc-3.3.6</literal> and <literal>gcc-4.1.1</literal>), then
  the derivation with the highest <emphasis>priority</emphasis> is
  used.  A derivation can define a priority by declaring the
  <varname>meta.priority</varname> attribute.  This attribute should
  be a number, with a higher value denoting a lower priority.  The
  default priority is <literal>0</literal>.</para>

  <para>If there are multiple matching derivations with the same
  priority, then the derivation with the highest version will be
  installed.</para>

  <para>You can force the installation of multiple derivations with
  the same name by being specific about the versions.  For instance,
  <literal>nix-env -i gcc-3.3.6 gcc-4.1.1</literal> will install both
  version of GCC (and will probably cause a user environment
  conflict!).</para></listitem>

  <listitem><para>If <link
  linkend='opt-attr'><option>--attr</option></link>
  (<option>-A</option>) is specified, the arguments are
  <emphasis>attribute paths</emphasis> that select attributes from the
  top-level Nix expression.  This is faster than using derivation
  names and unambiguous.  To find out the attribute paths of available
  packages, use <literal>nix-env -qaP</literal>.</para></listitem>

  <listitem><para>If <option>--from-profile</option>
  <replaceable>path</replaceable> is given,
  <replaceable>args</replaceable> is a set of names denoting installed
  store paths in the profile <replaceable>path</replaceable>.  This is
  an easy way to copy user environment elements from one profile to
  another.</para></listitem>

  <listitem><para>If <option>--from-expression</option> is given,
  <replaceable>args</replaceable> are Nix <link
  linkend="ss-functions">functions</link> that are called with the
  active Nix expression as their single argument.  The derivations
  returned by those function calls are installed.  This allows
  derivations to be specified in an unambiguous way, which is necessary
  if there are multiple derivations with the same
  name.</para></listitem>

  <listitem><para>If <replaceable>args</replaceable> are store
  derivations, then these are <link
  linkend="rsec-nix-store-realise">realised</link>, and the resulting
  output paths are installed.</para></listitem>

  <listitem><para>If <replaceable>args</replaceable> are store paths
  that are not store derivations, then these are <link
  linkend="rsec-nix-store-realise">realised</link> and
  installed.</para></listitem>

  <listitem><para>By default all outputs are installed for each derivation.
  That can be reduced by setting <literal>meta.outputsToInstall</literal>.
  </para></listitem> <!-- TODO: link nixpkgs docs on the ability to override those. -->

</itemizedlist>

</para>

</refsection>


<refsection><title>Flags</title>

<variablelist>

  <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term>

    <listitem><para>Use only derivations for which a substitute is
    registered, i.e., there is a pre-built binary available that can
    be downloaded in lieu of building the derivation.  Thus, no
    packages will be built from source.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--preserve-installed</option></term>
    <term><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>

  <varlistentry><term><option>--remove-all</option></term>
    <term><option>-r</option></term>

    <listitem><para>Remove all previously installed packages first.
    This is equivalent to running <literal>nix-env -e '.*'</literal>
    first, except that everything happens in a single
    transaction.</para></listitem>

  </varlistentry>

</variablelist>

</refsection>


<refsection xml:id='refsec-nix-env-install-examples'><title>Examples</title>

<para>To install a specific version of <command>gcc</command> from the
active Nix expression:

<screen>
$ nix-env --install gcc-3.3.2
installing `gcc-3.3.2'
uninstalling `gcc-3.1'</screen>

Note the previously installed version is removed, since
<option>--preserve-installed</option> was not specified.</para>

<para>To install an arbitrary version:

<screen>
$ nix-env --install gcc
installing `gcc-3.3.2'</screen>

</para>

<para>To install using a specific attribute:

<screen>
$ nix-env -i -A gcc40mips
$ nix-env -i -A xorg.xorgserver</screen>

</para>

<para>To install all derivations in the Nix expression <filename>foo.nix</filename>:

<screen>
$ nix-env -f ~/foo.nix -i '.*'</screen>

</para>

<para>To copy the store path with symbolic name <literal>gcc</literal>
from another profile:

<screen>
$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc</screen>

</para>

<para>To install a specific store derivation (typically created by
<command>nix-instantiate</command>):

<screen>
$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv</screen>

</para>

<para>To install a specific output path:

<screen>
$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3</screen>

</para>

<para>To install from a Nix expression specified on the command-line:

<screen>
$ nix-env -f ./foo.nix -i -E \
    'f: (f {system = "i686-linux";}).subversionWithJava'</screen>

I.e., this evaluates to <literal>(f: (f {system =
"i686-linux";}).subversionWithJava) (import ./foo.nix)</literal>, thus
selecting the <literal>subversionWithJava</literal> attribute from the
set returned by calling the function defined in
<filename>./foo.nix</filename>.</para>

<para>A dry-run tells you which paths will be downloaded or built from
source:

<screen>
$ nix-env -f '&lt;nixpkgs>' -iA hello --dry-run
(dry run; not doing anything)
installing ‘hello-2.10’
these paths will be fetched (0.04 MiB download, 0.19 MiB unpacked):
  /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
  <replaceable>...</replaceable></screen>

</para>

<para>To install Firefox from the latest revision in the Nixpkgs/NixOS
14.12 channel:

<screen>
$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox
</screen>

(The GitHub repository <literal>nixpkgs-channels</literal> is updated
automatically from the main <literal>nixpkgs</literal> repository
after certain tests have succeeded and binaries have been built and
uploaded to the binary cache at <uri>cache.nixos.org</uri>.)</para>

</refsection>

</refsection>



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

<refsection xml:id="rsec-nix-env-upgrade"><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>
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
  <group choice='opt'>
    <arg choice='plain'><option>--lt</option></arg>
    <arg choice='plain'><option>--leq</option></arg>
    <arg choice='plain'><option>--eq</option></arg>
    <arg choice='plain'><option>--always</option></arg>
  </group>
  <arg choice='plain' rep='repeat'><replaceable>args</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 store paths
are replaced for which there are newer versions in the set of paths
described by <replaceable>args</replaceable>.  Paths 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>args</replaceable>
matches no installed derivations.</para>

<para>For a description of how <replaceable>args</replaceable> is
mapped to a set of store paths, see <link
linkend="rsec-nix-env-install"><option>--install</option></link>.  If
<replaceable>args</replaceable> describes multiple store paths with
the same symbolic name, only the one with the highest version is
installed.</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
    “upgrade” 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 “synchronisation” between the installed and available
    derivations.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--eq</option></term>

    <listitem><para><emphasis>Only</emphasis> “upgrade” to derivations
    that have the same version.  This may not seem very useful, but it
    actually is, e.g., when there is a new release of Nixpkgs and you
    want to replace installed applications with the same versions
    built against newer dependencies (to reduce the number of
    dependencies floating around on your system).</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--always</option></term>

    <listitem><para>In addition to upgrading to newer versions, also
    “upgrade” 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>

<para>For the other flags, see <option
linkend="rsec-nix-env-install">--install</option>.</para>

</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 xml:id="ssec-version-comparisons"><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 followed 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 store
paths designated by the symbolic names
<replaceable>names</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 xml:id="rsec-nix-env-set"><title>Operation <option>--set</option></title>

<refsection><title>Synopsis</title>

<cmdsynopsis>
  <command>nix-env</command>
  <arg choice='plain'><option>--set</option></arg>
  <arg choice='plain'><replaceable>drvname</replaceable></arg>
</cmdsynopsis>
</refsection>

<refsection><title>Description</title>

<para>The <option>--set</option> operation modifies the current generation of a
profile so that it contains exactly the specified derivation, and nothing else.
</para>

</refsection>

<refsection><title>Examples</title>

<para>
The following updates a profile such that its current generation will contain
just Firefox:

<screen>
$ nix-env -p /nix/var/nix/profiles/browser --set firefox</screen>

</para>

</refsection>

</refsection>



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

<refsection xml:id="rsec-nix-env-set-flag"><title>Operation <option>--set-flag</option></title>

<refsection><title>Synopsis</title>

<cmdsynopsis>
  <command>nix-env</command>
  <arg choice='plain'><option>--set-flag</option></arg>
  <arg choice='plain'><replaceable>name</replaceable></arg>
  <arg choice='plain'><replaceable>value</replaceable></arg>
  <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
</cmdsynopsis>
</refsection>

<refsection><title>Description</title>

<para>The <option>--set-flag</option> operation allows meta attributes
of installed packages to be modified.  There are several attributes
that can be usefully modified, because they affect the behaviour of
<command>nix-env</command> or the user environment build
script:

<itemizedlist>

  <listitem><para><varname>priority</varname> can be changed to
  resolve filename clashes.  The user environment build script uses
  the <varname>meta.priority</varname> attribute of derivations to
  resolve filename collisions between packages.  Lower priority values
  denote a higher priority.  For instance, the GCC wrapper package and
  the Binutils package in Nixpkgs both have a file
  <filename>bin/ld</filename>, so previously if you tried to install
  both you would get a collision.  Now, on the other hand, the GCC
  wrapper declares a higher priority than Binutils, so the former’s
  <filename>bin/ld</filename> is symlinked in the user
  environment.</para></listitem>

  <listitem><para><varname>keep</varname> can be set to
  <literal>true</literal> to prevent the package from being upgraded
  or replaced.  This is useful if you want to hang on to an older
  version of a package.</para></listitem>

  <listitem><para><varname>active</varname> can be set to
  <literal>false</literal> to “disable” the package.  That is, no
  symlinks will be generated to the files of the package, but it
  remains part of the profile (so it won’t be garbage-collected).  It
  can be set back to <literal>true</literal> to re-enable the
  package.</para></listitem>

</itemizedlist>

</para>

</refsection>

<refsection><title>Examples</title>

<para>To prevent the currently installed Firefox from being upgraded:

<screen>
$ nix-env --set-flag keep true firefox</screen>

After this, <command>nix-env -u</command> will ignore Firefox.</para>

<para>To disable the currently installed Firefox, then install a new
Firefox while the old remains part of the profile:

<screen>
$ nix-env -q
firefox-2.0.0.9 <lineannotation>(the current one)</lineannotation>

$ nix-env --preserve-installed -i firefox-2.0.0.11
installing `firefox-2.0.0.11'
building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
collision between `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.11/bin/firefox'
  and `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.9/bin/firefox'.
<lineannotation>(i.e., can’t have two active at the same time)</lineannotation>

$ nix-env --set-flag active false firefox
setting flag on `firefox-2.0.0.9'

$ nix-env --preserve-installed -i firefox-2.0.0.11
installing `firefox-2.0.0.11'

$ nix-env -q
firefox-2.0.0.11 <lineannotation>(the enabled one)</lineannotation>
firefox-2.0.0.9 <lineannotation>(the disabled one)</lineannotation></screen>

</para>

<para>To make files from <literal>binutils</literal> take precedence
over files from <literal>gcc</literal>:

<screen>
$ nix-env --set-flag priority 5 binutils
$ nix-env --set-flag priority 10 gcc</screen>

</para>

</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>

  <sbr />

  <arg>
    <group choice='req'>
      <arg choice='plain'><option>--status</option></arg>
      <arg choice='plain'><option>-s</option></arg>
    </group>
  </arg>
  <arg>
    <group choice='req'>
      <arg choice='plain'><option>--attr-path</option></arg>
      <arg choice='plain'><option>-P</option></arg>
    </group>
  </arg>
  <arg><option>--no-name</option></arg>
  <arg>
    <group choice='req'>
      <arg choice='plain'><option>--compare-versions</option></arg>
      <arg choice='plain'><option>-c</option></arg>
    </group>
  </arg>
  <arg><option>--system</option></arg>
  <arg><option>--drv-path</option></arg>
  <arg><option>--out-path</option></arg>
  <arg><option>--description</option></arg>
  <arg><option>--meta</option></arg>

  <sbr />

  <arg><option>--xml</option></arg>
  <arg><option>--json</option></arg>
  <arg>
    <group choice='req'>
      <arg choice='plain'><option>--prebuilt-only</option></arg>
      <arg choice='plain'><option>-b</option></arg>
    </group>
  </arg>

  <arg>
    <group choice='req'>
      <arg choice='plain'><option>--attr</option></arg>
      <arg choice='plain'><option>-A</option></arg>
    </group>
    <replaceable>attribute-path</replaceable>
  </arg>

  <sbr />

  <arg choice='plain' rep='repeat'><replaceable>names</replaceable></arg>
</cmdsynopsis>

</refsection>


<refsection><title>Description</title>

<para>The query operation displays information about either the store
paths 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>).  It only prints information about
derivations whose symbolic name matches one of
<replaceable>names</replaceable>.</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 things on which the query
operates.</para>

<variablelist>

  <varlistentry><term><option>--installed</option></term>

    <listitem><para>The query operates on the store paths that are
    installed in the current generation of the active profile.  This
    is the default.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--available</option></term>
    <term><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.  Multiple flags may be specified, in which
case the information is shown in the order given here.  Note that the
name of the derivation is shown unless <option>--no-name</option> is
specified.</para>

<!-- TODO: fix the terminology here; i.e., derivations, store paths,
user environment elements, etc. -->

<variablelist>

  <varlistentry><term><option>--xml</option></term>

    <listitem><para>Print the result in an XML representation suitable
    for automatic processing by other tools.  The root element is
    called <literal>items</literal>, which contains a
    <literal>item</literal> element for each available or installed
    derivation.  The fields discussed below are all stored in
    attributes of the <literal>item</literal>
    elements.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--json</option></term>

    <listitem><para>Print the result in a JSON representation suitable
    for automatic processing by other tools.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term>

    <listitem><para>Show only derivations for which a substitute is
    registered, i.e., there is a pre-built binary available that can
    be downloaded in lieu of building the derivation.  Thus, this
    shows all packages that probably can be installed
    quickly.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--status</option></term>
    <term><option>-s</option></term>

    <listitem><para>Print the <emphasis>status</emphasis> of the
    derivation.  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>

  <varlistentry><term><option>--attr-path</option></term>
    <term><option>-P</option></term>

    <listitem><para>Print the <emphasis>attribute path</emphasis> of
    the derivation, which can be used to unambiguously select it using
    the <link linkend="opt-attr"><option>--attr</option> option</link>
    available in commands that install derivations like
    <literal>nix-env --install</literal>.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--no-name</option></term>

    <listitem><para>Suppress printing of the <literal>name</literal>
    attribute of each derivation.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--compare-versions</option> /
  <option>-c</option></term>

    <listitem><para>Compare installed versions to available versions,
    or vice versa (if <option>--available</option> is given).  This is
    useful for quickly seeing whether upgrades for installed
    packages are available in a Nix expression.  A column is added
    with the following meaning:

    <variablelist>

      <varlistentry><term><literal>&lt;</literal> <replaceable>version</replaceable></term>

        <listitem><para>A newer version of the package is available
        or installed.</para></listitem>

      </varlistentry>

      <varlistentry><term><literal>=</literal> <replaceable>version</replaceable></term>

        <listitem><para>At most the same version of the package is
        available or installed.</para></listitem>

      </varlistentry>

      <varlistentry><term><literal>></literal> <replaceable>version</replaceable></term>

        <listitem><para>Only older versions of the package are
        available or installed.</para></listitem>

      </varlistentry>

      <varlistentry><term><literal>- ?</literal></term>

        <listitem><para>No version of the package is available or
        installed.</para></listitem>

      </varlistentry>

    </variablelist>

    </para></listitem>

  </varlistentry>

  <varlistentry><term><option>--system</option></term>

    <listitem><para>Print the <literal>system</literal> attribute of
    the derivation.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--drv-path</option></term>

    <listitem><para>Print the path of the store
    derivation.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--out-path</option></term>

    <listitem><para>Print the output path of the
    derivation.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--description</option></term>

    <listitem><para>Print a short (one-line) description of the
    derivation, if available.  The description is taken from the
    <literal>meta.description</literal> attribute of the
    derivation.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--meta</option></term>

    <listitem><para>Print all of the meta-attributes of the
    derivation.  This option is only available with
    <option>--xml</option> or <option>--json</option>.</para></listitem>

  </varlistentry>

</variablelist>

</refsection>


<refsection><title>Examples</title>

<para>To show installed packages:

<screen>
$ nix-env -q
bison-1.875c
docbook-xml-4.2
firefox-1.0.4
MPlayer-1.0pre7
ORBit2-2.8.3
<replaceable>…</replaceable>
</screen>

</para>

<para>To show available packages:

<screen>
$ nix-env -qa
firefox-1.0.7
GConf-2.4.0.1
MPlayer-1.0pre7
ORBit2-2.8.3
<replaceable>…</replaceable>
</screen>

</para>

<para>To show the status of available packages:

<screen>
$ nix-env -qas
-P- firefox-1.0.7   <lineannotation>(not installed but present)</lineannotation>
--S GConf-2.4.0.1   <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation>
--S MPlayer-1.0pre3 <lineannotation>(i.e., this is not the installed MPlayer, even though the version is the same!)</lineannotation>
IP- ORBit2-2.8.3    <lineannotation>(installed and by definition present)</lineannotation>
<replaceable>…</replaceable>
</screen>

</para>

<para>To show available packages in the Nix expression <filename>foo.nix</filename>:

<screen>
$ nix-env -f ./foo.nix -qa
foo-1.2.3
</screen>

</para>

<para>To compare installed versions to what’s available:

<screen>
$ nix-env -qc
<replaceable>...</replaceable>
acrobat-reader-7.0 - ?      <lineannotation>(package is not available at all)</lineannotation>
autoconf-2.59      = 2.59   <lineannotation>(same version)</lineannotation>
firefox-1.0.4      &lt; 1.0.7  <lineannotation>(a more recent version is available)</lineannotation>
<replaceable>...</replaceable>
</screen>

</para>

<para>To show all packages with “<literal>zip</literal>” in the name:

<screen>
$ nix-env -qa '.*zip.*'
bzip2-1.0.6
gzip-1.6
zip-3.0
<replaceable>…</replaceable>
</screen>

</para>

<para>To show all packages with “<literal>firefox</literal>” or
“<literal>chromium</literal>” in the name:

<screen>
$ nix-env -qa '.*(firefox|chromium).*'
chromium-37.0.2062.94
chromium-beta-38.0.2125.24
firefox-32.0.3
firefox-with-plugins-13.0.1
<replaceable>…</replaceable>
</screen>

</para>

<para>To show all packages in the latest revision of the Nixpkgs
repository:

<screen>
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
</screen>

</para>

</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='plain'><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='plain'><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, the
special value <literal>old</literal> to delete all non-current
generations,  a value such as <literal>30d</literal> to delete all
generations older than the specified number of days (except for the
generation that was active at that point in time), or a value such as
<literal>+5</literal> to keep the last <literal>5</literal> generations
ignoring any newer than current, e.g., if <literal>30</literal> is the current
generation <literal>+5</literal> will delete generation <literal>25</literal>
and all older 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 --delete-generations +5

$ nix-env --delete-generations 30d

$ 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='plain'><option>--rollback</option></arg>
</cmdsynopsis>

</refsection>

<refsection><title>Description</title>

<para>This operation switches to the “previous” 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 --rollback
error: no generation older than the current (91) exists</screen>

</refsection>

</refsection>


<refsection condition="manpage"><title>Environment variables</title>

<variablelist>

  <varlistentry><term><envar>NIX_PROFILE</envar></term>

    <listitem><para>Location of the Nix profile.  Defaults to the
    target of the symlink <filename>~/.nix-profile</filename>, if it
    exists, or <filename>/nix/var/nix/profiles/default</filename>
    otherwise.</para></listitem>

  </varlistentry>

  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
</variablelist>

</refsection>


</refentry>