<refentry>
<refnamediv>
<refname>nix-env</refname>
<refpurpose>manipulate or query Nix user environments</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-env</command>
&opt-common-syn;
<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>--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>
&opt-common;
<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>
</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>--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>
