<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. See also <xref
linkend="sec-common-options" />.
</para>
<variablelist>
<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 < 2.3
2.1 < 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 < 2.3
2.3pre3 < 2.3pre12
2.3a < 2.3c
2.3pre1 < 2.3c
2.3pre1 < 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>
