.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix-env" "1" ""
.SH Name
\fCnix-env\fR - manipulate or query Nix user environments
.SH Synopsis
\fCnix-env\fR
[\fC--option\fR \fIname\fR \fIvalue\fR]
[\fC--arg\fR \fIname\fR \fIvalue\fR]
[\fC--argstr\fR \fIname\fR \fIvalue\fR]
[{\fC--file\fR | \fC-f\fR} \fIpath\fR]
[{\fC--profile\fR | \fC-p\fR} *path(]
[\fC--system-filter\fR \fIsystem\fR]
[\fC--dry-run\fR]
\fIoperation\fR [\fIoptions…\fR] [\fIarguments…\fR]
.SH Description
The command \fCnix-env\fR 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.
.PP
\fCnix-env\fR takes exactly one \fIoperation\fR flag which indicates the
subcommand to be performed. These are documented below.
.SH Selectors
Several commands, such as \fCnix-env -q\fR and \fCnix-env -i\fR, 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 regex7.) 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:
.IP "\(bu" 2
\fCfirefox\fR
.br
Matches the package name \fCfirefox\fR and any version.
.IP "\(bu" 2
\fCfirefox-32.0\fR
.br
Matches the package name \fCfirefox\fR and version \fC32.0\fR.
.IP "\(bu" 2
\fCgtk\e\e+\fR
.br
Matches the package name \fCgtk+\fR. The \fC+\fR 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.
.IP "\(bu" 2
\fC.\e*\fR
.br
Matches any package name. This is the default for most commands.
.IP "\(bu" 2
\fC'.*zip.*'\fR
.br
Matches any package name containing the string \fCzip\fR. Note the dots:
\fC'*zip*'\fR does not work, because in a regular expression, the
character \fC*\fR is interpreted as a quantifier.
.IP "\(bu" 2
\fC'.*(firefox|chromium).*'\fR
.br
Matches any package name containing the strings \fCfirefox\fR or
\fCchromium\fR.
.SH Common options
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.
.IP "\(bu" 2
\fC--file\fR / \fC-f\fR \fIpath\fR
.br
Specifies the Nix expression (designated below as the \fIactive Nix
expression\fR) used by the \fC--install\fR, \fC--upgrade\fR, and \fC--query
--available\fR operations to obtain derivations. The default is
\fC\(ti/.nix-defexpr\fR.
.IP
If the argument starts with \fChttp://\fR or \fChttps://\fR, 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 \fCdefault.nix\fR.
.IP "\(bu" 2
\fC--profile\fR / \fC-p\fR \fIpath\fR
.br
Specifies the profile to be used by those operations that operate on
a profile (designated below as the \fIactive profile\fR). A profile is a
sequence of user environments called \fIgenerations\fR, one of which is
the \fIcurrent generation\fR.
.IP "\(bu" 2
\fC--dry-run\fR
.br
For the \fC--install\fR, \fC--upgrade\fR, \fC--uninstall\fR,
\fC--switch-generation\fR, \fC--delete-generations\fR and \fC--rollback\fR
operations, this flag will cause \fCnix-env\fR to print what \fIwould\fR be
done if this flag had not been specified, without actually doing it.
.IP
\fC--dry-run\fR also prints out which paths will be
\fBsubstituted\fR (\fI../glossary.md\fR) (i.e., downloaded) and which paths
will be built from source (because no substitute is available).
.IP "\(bu" 2
\fC--system-filter\fR \fIsystem\fR
.br
By default, operations such as \fC--query
--available\fR show derivations matching any platform. This option
allows you to use derivations for the specified platform \fIsystem\fR.
.SH Files
.IP "\(bu" 2
\fC\(ti/.nix-defexpr\fR
.br
The source for the default Nix expressions used by the
\fC--install\fR, \fC--upgrade\fR, and \fC--query --available\fR operations to
obtain derivations. The \fC--file\fR option may be used to override
this default.
.IP
If \fC\(ti/.nix-defexpr\fR 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.
.IP
If \fC\(ti/.nix-defexpr\fR is a directory containing a \fCdefault.nix\fR file,
that file is loaded as in the above paragraph.
.IP
If \fC\(ti/.nix-defexpr\fR is a directory without a \fCdefault.nix\fR 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.
.IP
For example, if \fC\(ti/.nix-defexpr\fR contains two files, \fCfoo.nix\fR and
\fCbar.nix\fR, then the default Nix expression will essentially be
.LP
.EX
{
  foo = import \(ti/.nix-defexpr/foo.nix;
  bar = import \(ti/.nix-defexpr/bar.nix;
}
.EE
.IP
The file \fCmanifest.nix\fR is always ignored. Subdirectories without a
\fCdefault.nix\fR 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.
.IP
The command \fCnix-channel\fR places symlinks to the downloaded Nix
expressions from each subscribed channel in this directory.
.IP "\(bu" 2
\fC\(ti/.nix-profile\fR
.br
A symbolic link to the user\[u2019]s current profile. By default, this
symlink points to \fCprefix/var/nix/profiles/default\fR. The \fCPATH\fR
environment variable should include \fC\(ti/.nix-profile/bin\fR for the
user environment to be visible to the user.
.SH Operation \fC--install\fR
.SS Synopsis
\fCnix-env\fR {\fC--install\fR | \fC-i\fR} \fIargs…\fR
[{\fC--prebuilt-only\fR | \fC-b\fR}]
[{\fC--attr\fR | \fC-A\fR}]
[\fC--from-expression\fR] [\fC-E\fR]
[\fC--from-profile\fR \fIpath\fR]
[\fC--preserve-installed\fR | \fC-P\fR]
[\fC--remove-all\fR | \fC-r\fR]
.SS Description
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 \fIargs\fR is added. The arguments \fIargs\fR map to store paths in
a number of possible ways:
.IP "\(bu" 2
By default, \fIargs\fR 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 \fC--preserve-installed\fR is specified.
.IP
If there are multiple derivations matching a name in \fIargs\fR that
have the same name (e.g., \fCgcc-3.3.6\fR and \fCgcc-4.1.1\fR), then the
derivation with the highest \fIpriority\fR is used. A derivation can
define a priority by declaring the \fCmeta.priority\fR attribute. This
attribute should be a number, with a higher value denoting a lower
priority. The default priority is \fC0\fR.
.IP
If there are multiple matching derivations with the same priority,
then the derivation with the highest version will be installed.
.IP
You can force the installation of multiple derivations with the same
name by being specific about the versions. For instance, \fCnix-env -i
gcc-3.3.6 gcc-4.1.1\fR will install both version of GCC (and will
probably cause a user environment conflict!).
.IP "\(bu" 2
If \fC--attr\fR (\fC-A\fR) is specified, the arguments are \fIattribute
paths\fR 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 \fCnix-env -qaP\fR.
.IP "\(bu" 2
If \fC--from-profile\fR \fIpath\fR is given, \fIargs\fR is a set of names
denoting installed store paths in the profile \fIpath\fR. This is an
easy way to copy user environment elements from one profile to
another.
.IP "\(bu" 2
If \fC--from-expression\fR is given, \fIargs\fR are Nix
\fBfunctions\fR (\fI../expressions/language-constructs.md#functions\fR)
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.
.IP "\(bu" 2
If \fIargs\fR are store derivations, then these are
\fBrealised\fR (\fInix-store.md#operation---realise\fR), and the resulting output paths
are installed.
.IP "\(bu" 2
If \fIargs\fR are store paths that are not store derivations, then these
are \fBrealised\fR (\fInix-store.md#operation---realise\fR) and installed.
.IP "\(bu" 2
By default all outputs are installed for each derivation. That can
be reduced by setting \fCmeta.outputsToInstall\fR.
.SS Flags
.IP "\(bu" 2
\fC--prebuilt-only\fR / \fC-b\fR
.br
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.
.IP "\(bu" 2
\fC--preserve-installed\fR; \fC-P\fR
.br
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.
.IP "\(bu" 2
\fC--remove-all\fR; \fC-r\fR
.br
Remove all previously installed packages first. This is equivalent
to running \fCnix-env -e '.*'\fR first, except that everything happens
in a single transaction.
.SS Examples
To install a package using a specific attribute path from the active Nix expression:
.LP
.EX
$ nix-env -iA gcc40mips
installing \(gagcc-4.0.2'
$ nix-env -iA xorg.xorgserver
installing \(gaxorg-server-1.2.0'
.EE
.PP
To install a specific version of \fCgcc\fR using the derivation name:
.LP
.EX
$ nix-env --install gcc-3.3.2
installing \(gagcc-3.3.2'
uninstalling \(gagcc-3.1'
.EE
.PP
Using attribute path for selecting a package is preferred,
as it is much faster and there will not be multiple matches.
.PP
Note the previously installed version is removed, since
\fC--preserve-installed\fR was not specified.
.PP
To install an arbitrary version:
.LP
.EX
$ nix-env --install gcc
installing \(gagcc-3.3.2'
.EE
.PP
To install all derivations in the Nix expression \fCfoo.nix\fR:
.LP
.EX
$ nix-env -f \(ti/foo.nix -i '.*'
.EE
.PP
To copy the store path with symbolic name \fCgcc\fR from another profile:
.LP
.EX
$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
.EE
.PP
To install a specific store derivation (typically created by
\fCnix-instantiate\fR):
.LP
.EX
$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
.EE
.PP
To install a specific output path:
.LP
.EX
$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
.EE
.PP
To install from a Nix expression specified on the command-line:
.LP
.EX
$ nix-env -f ./foo.nix -i -E \e
    'f: (f {system = \(dqi686-linux\(dq;}).subversionWithJava'
.EE
.PP
I.e., this evaluates to \fC(f: (f {system =
\(dqi686-linux\(dq;}).subversionWithJava) (import ./foo.nix)\fR, thus selecting
the \fCsubversionWithJava\fR attribute from the set returned by calling the
function defined in \fC./foo.nix\fR.
.PP
A dry-run tells you which paths will be downloaded or built from source:
.LP
.EX
$ nix-env -f '<nixpkgs>' -iA hello --dry-run
(dry run; not doing anything)
installing ‘hello-2.10’
this path will be fetched (0.04 MiB download, 0.19 MiB unpacked):
  /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
  ...
.EE
.PP
To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12
channel:
.LP
.EX
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
.EE
.SH Operation \fC--upgrade\fR
.SS Synopsis
\fCnix-env\fR {\fC--upgrade\fR | \fC-u\fR} \fIargs\fR
[\fC--lt\fR | \fC--leq\fR | \fC--eq\fR | \fC--always\fR]
[{\fC--prebuilt-only\fR | \fC-b\fR}]
[{\fC--attr\fR | \fC-A\fR}]
[\fC--from-expression\fR] [\fC-E\fR]
[\fC--from-profile\fR \fIpath\fR]
[\fC--preserve-installed\fR | \fC-P\fR]
.SS Description
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 \fIargs\fR. 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 \fIargs\fR matches no installed derivations.
.PP
For a description of how \fIargs\fR is mapped to a set of store paths, see
\fB\fC--install\fR\fR (\fI#operation---install\fR). If \fIargs\fR describes multiple
store paths with the same symbolic name, only the one with the highest
version is installed.
.SS Flags
.IP "\(bu" 2
\fC--lt\fR
.br
Only upgrade a derivation to newer versions. This is the default.
.IP "\(bu" 2
\fC--leq\fR
.br
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.
.IP "\(bu" 2
\fC--eq\fR
.br
\fIOnly\fR “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).
.IP "\(bu" 2
\fC--always\fR
.br
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.
.LP
For the other flags, see \fC--install\fR.
.SS Examples
.LP
.EX
$ nix-env --upgrade -A nixpkgs.gcc
upgrading \(gagcc-3.3.1' to \(gagcc-3.4'
.EE
.PP
When there are no updates available, nothing will happen:
.LP
.EX
$ nix-env --upgrade -A nixpkgs.pan
.EE
.PP
Using \fC-A\fR is preferred when possible, as it is faster and unambiguous but
it is also possible to upgrade to a specific version by matching the derivation name:
.LP
.EX
$ nix-env -u gcc-3.3.2 --always
upgrading \(gagcc-3.4' to \(gagcc-3.3.2'
.EE
.PP
To try to upgrade everything
(matching packages based on the part of the derivation name without version):
.LP
.EX
$ nix-env -u
upgrading \(gahello-2.1.2' to \(gahello-2.1.3'
upgrading \(gamozilla-1.2' to \(gamozilla-1.4'
.EE
.SS Versions
The upgrade operation determines whether a derivation \fCy\fR is an upgrade
of a derivation \fCx\fR by looking at their respective \fCname\fR attributes.
The names (e.g., \fCgcc-3.3.1\fR are split into two parts: the package name
(\fCgcc\fR), and the version (\fC3.3.1\fR). The version part starts after the
first dash not followed by a letter. \fCx\fR is considered an upgrade of \fCy\fR
if their package names match, and the version of \fCy\fR is higher than that
of \fCx\fR.
.PP
The versions are compared by splitting them into contiguous components
of numbers and letters. E.g., \fC3.3.1pre5\fR is split into \fC[3, 3, 1,
\(dqpre\(dq, 5]\fR. These lists are then compared lexicographically (from left
to right). Corresponding components \fCa\fR and \fCb\fR are compared as follows.
If they are both numbers, integer comparison is used. If \fCa\fR is an empty
string and \fCb\fR is a number, \fCa\fR is considered less than \fCb\fR. The special
string component \fCpre\fR (for \fIpre-release\fR) 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).
.PP
This is illustrated by the following examples:
.LP
.EX
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
.EE
.SH Operation \fC--uninstall\fR
.SS Synopsis
\fCnix-env\fR {\fC--uninstall\fR | \fC-e\fR} \fIdrvnames…\fR
.SS Description
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 \fIdrvnames\fR are removed.
.SS Examples
.LP
.EX
$ nix-env --uninstall gcc
$ nix-env -e '.*' (remove everything)
.EE
.SH Operation \fC--set\fR
.SS Synopsis
\fCnix-env\fR \fC--set\fR \fIdrvname\fR
.SS Description
The \fC--set\fR operation modifies the current generation of a profile so
that it contains exactly the specified derivation, and nothing else.
.SS Examples
The following updates a profile such that its current generation will
contain just Firefox:
.LP
.EX
$ nix-env -p /nix/var/nix/profiles/browser --set firefox
.EE
.SH Operation \fC--set-flag\fR
.SS Synopsis
\fCnix-env\fR \fC--set-flag\fR \fIname\fR \fIvalue\fR \fIdrvnames\fR
.SS Description
The \fC--set-flag\fR 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 \fCnix-env\fR or the user
environment build script:
.IP "\(bu" 2
\fCpriority\fR can be changed to resolve filename clashes. The user
environment build script uses the \fCmeta.priority\fR 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
\fCbin/ld\fR, 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 \fCbin/ld\fR is symlinked in the
user environment.
.IP "\(bu" 2
\fCkeep\fR can be set to \fCtrue\fR 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.
.IP "\(bu" 2
\fCactive\fR can be set to \fCfalse\fR 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 \fCtrue\fR to re-enable the package.
.SS Examples
To prevent the currently installed Firefox from being upgraded:
.LP
.EX
$ nix-env --set-flag keep true firefox
.EE
.PP
After this, \fCnix-env -u\fR will ignore Firefox.
.PP
To disable the currently installed Firefox, then install a new Firefox
while the old remains part of the profile:
.LP
.EX
$ nix-env -q
firefox-2.0.0.9 (the current one)

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

$ nix-env --set-flag active false firefox
setting flag on \(gafirefox-2.0.0.9'

$ nix-env --preserve-installed -i firefox-2.0.0.11
installing \(gafirefox-2.0.0.11'

$ nix-env -q
firefox-2.0.0.11 (the enabled one)
firefox-2.0.0.9 (the disabled one)
.EE
.PP
To make files from \fCbinutils\fR take precedence over files from \fCgcc\fR:
.LP
.EX
$ nix-env --set-flag priority 5 binutils
$ nix-env --set-flag priority 10 gcc
.EE
.SH Operation \fC--query\fR
.SS Synopsis
\fCnix-env\fR {\fC--query\fR | \fC-q\fR} \fInames…\fR
[\fC--installed\fR | \fC--available\fR | \fC-a\fR]
[{\fC--status\fR | \fC-s\fR}]
[{\fC--attr-path\fR | \fC-P\fR}]
[\fC--no-name\fR]
[{\fC--compare-versions\fR | \fC-c\fR}]
[\fC--system\fR]
[\fC--drv-path\fR]
[\fC--out-path\fR]
[\fC--description\fR]
[\fC--meta\fR]
[\fC--xml\fR]
[\fC--json\fR]
[{\fC--prebuilt-only\fR | \fC-b\fR}]
[{\fC--attr\fR | \fC-A\fR} \fIattribute-path\fR]
.SS Description
The query operation displays information about either the store paths
that are installed in the current generation of the active profile
(\fC--installed\fR), or the derivations that are available for installation
in the active Nix expression (\fC--available\fR). It only prints information
about derivations whose symbolic name matches one of \fInames\fR.
.PP
The derivations are sorted by their \fCname\fR attributes.
.SS Source selection
The following flags specify the set of things on which the query
operates.
.IP "\(bu" 2
\fC--installed\fR
.br
The query operates on the store paths that are installed in the
current generation of the active profile. This is the default.
.IP "\(bu" 2
\fC--available\fR; \fC-a\fR
.br
The query operates on the derivations that are available in the
active Nix expression.
.SS Queries
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 \fC--no-name\fR is specified.
.IP "\(bu" 2
\fC--xml\fR
.br
Print the result in an XML representation suitable for automatic
processing by other tools. The root element is called \fCitems\fR, which
contains a \fCitem\fR element for each available or installed
derivation. The fields discussed below are all stored in attributes
of the \fCitem\fR elements.
.IP "\(bu" 2
\fC--json\fR
.br
Print the result in a JSON representation suitable for automatic
processing by other tools.
.IP "\(bu" 2
\fC--prebuilt-only\fR / \fC-b\fR
.br
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.
.IP "\(bu" 2
\fC--status\fR; \fC-s\fR
.br
Print the \fIstatus\fR of the derivation. The status consists of three
characters. The first is \fCI\fR or \fC-\fR, indicating whether the
derivation is currently installed in the current generation of the
active profile. This is by definition the case for \fC--installed\fR,
but not for \fC--available\fR. The second is \fCP\fR or \fC-\fR, 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 \fCS\fR or \fC-\fR, indicating whether
a substitute is available for the derivation.
.IP "\(bu" 2
\fC--attr-path\fR; \fC-P\fR
.br
Print the \fIattribute path\fR of the derivation, which can be used to
unambiguously select it using the \fC--attr\fR option available in
commands that install derivations like \fCnix-env --install\fR. This
option only works together with \fC--available\fR
.IP "\(bu" 2
\fC--no-name\fR
.br
Suppress printing of the \fCname\fR attribute of each derivation.
.IP "\(bu" 2
\fC--compare-versions\fR / \fC-c\fR
.br
Compare installed versions to available versions, or vice versa (if
\fC--available\fR 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:
.RS
.IP "\(bu" 2
\fC<\fR \fIversion\fR
.br
A newer version of the package is available or installed.
.IP "\(bu" 2
\fC=\fR \fIversion\fR
.br
At most the same version of the package is available or
installed.
.IP "\(bu" 2
\fC>\fR \fIversion\fR
.br
Only older versions of the package are available or installed.
.IP "\(bu" 2
\fC- ?\fR
.br
No version of the package is available or installed.
.RE
.IP "\(bu" 2
\fC--system\fR
.br
Print the \fCsystem\fR attribute of the derivation.
.IP "\(bu" 2
\fC--drv-path\fR
.br
Print the path of the store derivation.
.IP "\(bu" 2
\fC--out-path\fR
.br
Print the output path of the derivation.
.IP "\(bu" 2
\fC--description\fR
.br
Print a short (one-line) description of the derivation, if
available. The description is taken from the \fCmeta.description\fR
attribute of the derivation.
.IP "\(bu" 2
\fC--meta\fR
.br
Print all of the meta-attributes of the derivation. This option is
only available with \fC--xml\fR or \fC--json\fR.
.SS Examples
To show installed packages:
.LP
.EX
$ nix-env -q
bison-1.875c
docbook-xml-4.2
firefox-1.0.4
MPlayer-1.0pre7
ORBit2-2.8.3
…
.EE
.PP
To show available packages:
.LP
.EX
$ nix-env -qa
firefox-1.0.7
GConf-2.4.0.1
MPlayer-1.0pre7
ORBit2-2.8.3
…
.EE
.PP
To show the status of available packages:
.LP
.EX
$ nix-env -qas
-P- firefox-1.0.7   (not installed but present)
--S GConf-2.4.0.1   (not present, but there is a substitute for fast installation)
--S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
IP- ORBit2-2.8.3    (installed and by definition present)
…
.EE
.PP
To show available packages in the Nix expression \fCfoo.nix\fR:
.LP
.EX
$ nix-env -f ./foo.nix -qa
foo-1.2.3
.EE
.PP
To compare installed versions to what’s available:
.LP
.EX
$ nix-env -qc
\&...
acrobat-reader-7.0 - ?      (package is not available at all)
autoconf-2.59      = 2.59   (same version)
firefox-1.0.4      < 1.0.7  (a more recent version is available)
\&...
.EE
.PP
To show all packages with “\fCzip\fR” in the name:
.LP
.EX
$ nix-env -qa '.*zip.*'
bzip2-1.0.6
gzip-1.6
zip-3.0
…
.EE
.PP
To show all packages with “\fCfirefox\fR” or “\fCchromium\fR” in the name:
.LP
.EX
$ 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
…
.EE
.PP
To show all packages in the latest revision of the Nixpkgs repository:
.LP
.EX
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
.EE
.SH Operation \fC--switch-profile\fR
.SS Synopsis
\fCnix-env\fR {\fC--switch-profile\fR | \fC-S\fR} \fIpath\fR
.SS Description
This operation makes \fIpath\fR the current profile for the user. That is,
the symlink \fC\(ti/.nix-profile\fR is made to point to \fIpath\fR.
.SS Examples
.LP
.EX
$ nix-env -S \(ti/my-profile
.EE
.SH Operation \fC--list-generations\fR
.SS Synopsis
\fCnix-env\fR \fC--list-generations\fR
.SS Description
This operation print a list of all the currently existing generations
for the active profile. These may be switched to using the
\fC--switch-generation\fR operation. It also prints the creation date of the
generation, and indicates the current generation.
.SS Examples
.LP
.EX
$ 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)
.EE
.SH Operation \fC--delete-generations\fR
.SS Synopsis
\fCnix-env\fR \fC--delete-generations\fR \fIgenerations\fR
.SS Description
This operation deletes the specified generations of the current profile.
The generations can be a list of generation numbers, the special value
\fCold\fR to delete all non-current generations, a value such as \fC30d\fR 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 \fC+5\fR to keep the last \fC5\fR generations ignoring any newer than
current, e.g., if \fC30\fR is the current generation \fC+5\fR will delete
generation \fC25\fR and all older generations. Periodically deleting old
generations is important to make garbage collection effective.
.SS Examples
.LP
.EX
$ nix-env --delete-generations 3 4 8
.EE
.LP
.EX
$ nix-env --delete-generations +5
.EE
.LP
.EX
$ nix-env --delete-generations 30d
.EE
.LP
.EX
$ nix-env -p other_profile --delete-generations old
.EE
.SH Operation \fC--switch-generation\fR
.SS Synopsis
\fCnix-env\fR {\fC--switch-generation\fR | \fC-G\fR} \fIgeneration\fR
.SS Description
This operation makes generation number \fIgeneration\fR the current
generation of the active profile. That is, if the \fCprofile\fR is the path
to the active profile, then the symlink \fCprofile\fR is made to point to
\fCprofile-generation-link\fR, which is in turn a symlink to the actual user
environment in the Nix store.
.PP
Switching will fail if the specified generation does not exist.
.SS Examples
.LP
.EX
$ nix-env -G 42
switching from generation 50 to 42
.EE
.SH Operation \fC--rollback\fR
.SS Synopsis
\fCnix-env\fR \fC--rollback\fR
.SS Description
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
\fC--list-generations\fR and \fC--switch-generation\fR.
.SS Examples
.LP
.EX
$ nix-env --rollback
switching from generation 92 to 91
.EE
.LP
.EX
$ nix-env --rollback
error: no generation older than the current (91) exists
.EE
.SH Environment variables
.IP "\(bu" 2
\fCNIX_PROFILE\fR
.br
Location of the Nix profile. Defaults to the target of the symlink
\fC\(ti/.nix-profile\fR, if it exists, or \fC/nix/var/nix/profiles/default\fR
otherwise.