table of contents
- NAME
- SYNOPSIS
- DESCRIPTION
- SELECTORS
- COMMON OPTIONS
- FILES
- OPERATION --INSTALL
- OPERATION --UPGRADE
- OPERATION --UNINSTALL
- OPERATION --SET
- OPERATION --SET-FLAG
- OPERATION --QUERY
- OPERATION --SWITCH-PROFILE
- OPERATION --LIST-GENERATIONS
- OPERATION --DELETE-GENERATIONS
- OPERATION --SWITCH-GENERATION
- OPERATION --ROLLBACK
- ENVIRONMENT VARIABLES
- AUTHOR
- COPYRIGHT
NIX-ENV(1) | Command Reference | NIX-ENV(1) |
NAME¶
nix-env - manipulate or query Nix user environments
SYNOPSIS¶
nix-env [--help] [--version]
[{--verbose | -v}...] [--quiet]
[--no-build-output | -Q]
[{--max-jobs | -j} number]
[--cores number]
[--max-silent-time number]
[--timeout number]
[--keep-going | -k]
[--keep-failed | -K] [--fallback]
[--readonly-mode] [-I path]
[--option name value]
[--arg name value]
[--argstr name value]
[{--file | -f} path]
[{--profile | -p} path]
[--system-filter system] [--dry-run]
operation [options...] [arguments...]
DESCRIPTION¶
The command nix-env 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.
nix-env takes exactly one operation flag which indicates the subcommand to be performed. These are documented below.
SELECTORS¶
Several commands, such as nix-env -q and nix-env -i, 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 regex(7).) 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:
firefox
firefox-32.0
gtk\\+
.\*
'.*zip.*'
'.*(firefox|chromium).*'
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.
--file / -f path
If the argument starts with http:// or https://, 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 default.nix.
--profile / -p path
--dry-run
--dry-run also prints out which paths will be substituted (i.e., downloaded) and which paths will be built from source (because no substitute is available).
--system-filter system
--help
--version
--verbose / -v
This option may be specified repeatedly. Currently, the following verbosity levels exist:
0
1
2
3
4
5
--quiet
This option may be specified repeatedly. See the previous verbosity levels list.
--no-build-output / -Q
--max-jobs / -j number
Setting it to 0 disallows building on the local machine, which is useful when you want builds to happen only on remote builders.
--cores
--max-silent-time
--timeout
--keep-going / -k
--keep-failed / -K
--fallback
The most common scenario in which this is useful is when we have registered substitutes in order to perform binary distribution from, say, a network repository. If the repository is down, the realisation of the derivation will fail. When this option is specified, Nix will build the derivation instead. Thus, installation from binaries falls back on installation from source. This option is not the default since it is generally not desirable for a transient failure in obtaining the substitutes to lead to a full build from source (with the related consumption of resources).
--no-build-hook
It's useful in cases where the bandwidth between the client and the remote builder is too low. In that case it can take more time to upload the sources to the remote builder and fetch back the result than to do the computation locally.
--readonly-mode
--arg name value
For instance, the top-level default.nix in Nixpkgs is actually a function:
{ # The system (e.g., `i686-linux') for which to build the packages.
system ? builtins.currentSystem
... }: ...
So if you call this Nix expression (e.g., when you do nix-env -i pkgname), the function will be called automatically using the value builtins.currentSystem for the system argument. You can override this using --arg, e.g., nix-env -i pkgname --arg system \"i686-freebsd\". (Note that since the argument is a Nix string literal, you have to escape the quotes.)
--argstr name value
--attr / -A attrPath
In addition to attribute names, you can also specify array indices. For instance, the attribute path foo.3.bar selects the bar attribute of the fourth element of the array in the foo attribute of the top-level expression.
--expr / -E
-I path
--option name value
--repair
FILES¶
~/.nix-defexpr
If ~/.nix-defexpr 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.
If ~/.nix-defexpr is a directory containing a default.nix file, that file is loaded as in the above paragraph.
If ~/.nix-defexpr is a directory without a default.nix 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.
For example, if ~/.nix-defexpr contains two files, foo.nix and bar.nix, then the default Nix expression will essentially be
{
foo = import ~/.nix-defexpr/foo.nix;
bar = import ~/.nix-defexpr/bar.nix; }
The file manifest.nix is always ignored. Subdirectories without a default.nix 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.
The command nix-channel places symlinks to the downloaded Nix expressions from each subscribed channel in this directory.
~/.nix-profile
OPERATION --INSTALL¶
Synopsis¶
nix-env {--install | -i} [{--prebuilt-only | -b}] [{--attr | -A}] [--from-expression] [-E] [--from-profile path] [--preserve-installed | -P] [--remove-all | -r] args...
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 args is added. The arguments args map to store paths in a number of possible ways:
If there are multiple derivations matching a name in args that have the same name (e.g., gcc-3.3.6 and gcc-4.1.1), then the derivation with the highest priority is used. A derivation can define a priority by declaring the meta.priority attribute. This attribute should be a number, with a higher value denoting a lower priority. The default priority is 0.
If there are multiple matching derivations with the same priority, then the derivation with the highest version will be installed.
You can force the installation of multiple derivations with the same name by being specific about the versions. For instance, nix-env -i gcc-3.3.6 gcc-4.1.1 will install both version of GCC (and will probably cause a user environment conflict!).
Flags¶
--prebuilt-only / -b
--preserve-installed, -P
--remove-all, -r
Examples¶
To install a specific version of gcc from the active Nix expression:
$ nix-env --install gcc-3.3.2 installing `gcc-3.3.2' uninstalling `gcc-3.1'
Note the previously installed version is removed, since --preserve-installed was not specified.
To install an arbitrary version:
$ nix-env --install gcc installing `gcc-3.3.2'
To install using a specific attribute:
$ nix-env -i -A gcc40mips $ nix-env -i -A xorg.xorgserver
To install all derivations in the Nix expression foo.nix:
$ nix-env -f ~/foo.nix -i '.*'
To copy the store path with symbolic name gcc from another profile:
$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
To install a specific store derivation (typically created by nix-instantiate):
$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
To install a specific output path:
$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
To install from a Nix expression specified on the command-line:
$ nix-env -f ./foo.nix -i -E \
'f: (f {system = "i686-linux";}).subversionWithJava'
I.e., this evaluates to (f: (f {system = "i686-linux";}).subversionWithJava) (import ./foo.nix), thus selecting the subversionWithJava attribute from the set returned by calling the function defined in ./foo.nix.
A dry-run tells you which paths will be downloaded or built from source:
$ nix-env -f '<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
...
To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12 channel:
$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox
(The GitHub repository nixpkgs-channels is updated automatically from the main nixpkgs repository after certain tests have succeeded and binaries have been built and uploaded to the binary cache at cache.nixos.org.)
OPERATION --UPGRADE¶
Synopsis¶
nix-env {--upgrade | -u} [{--prebuilt-only | -b}] [{--attr | -A}] [--from-expression] [-E] [--from-profile path] [--lt | --leq | --eq | --always] args...
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 args. 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 args matches no installed derivations.
For a description of how args is mapped to a set of store paths, see --install. If args describes multiple store paths with the same symbolic name, only the one with the highest version is installed.
Flags¶
--lt
--leq
--eq
--always
For the other flags, see --install.
Examples¶
$ nix-env --upgrade gcc upgrading `gcc-3.3.1' to `gcc-3.4' $ nix-env -u gcc-3.3.2 --always (switch to a specific version) upgrading `gcc-3.4' to `gcc-3.3.2' $ nix-env --upgrade pan (no upgrades available, so nothing happens) $ nix-env -u (try to upgrade everything) upgrading `hello-2.1.2' to `hello-2.1.3' upgrading `mozilla-1.2' to `mozilla-1.4'
Versions¶
The upgrade operation determines whether a derivation y is an upgrade of a derivation x by looking at their respective name attributes. The names (e.g., gcc-3.3.1 are split into two parts: the package name (gcc), and the version (3.3.1). The version part starts after the first dash not followed by a letter. x is considered an upgrade of y if their package names match, and the version of y is higher that that of x.
The versions are compared by splitting them into contiguous components of numbers and letters. E.g., 3.3.1pre5 is split into [3, 3, 1, "pre", 5]. These lists are then compared lexicographically (from left to right). Corresponding components a and b are compared as follows. If they are both numbers, integer comparison is used. If a is an empty string and b is a number, a is considered less than b. The special string component pre (for pre-release) 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).
This is illustrated by the following examples:
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
OPERATION --UNINSTALL¶
Synopsis¶
nix-env {--uninstall | -e} drvnames...
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 names are removed.
Examples¶
$ nix-env --uninstall gcc $ nix-env -e '.*' (remove everything)
OPERATION --SET¶
Synopsis¶
nix-env --set drvname
Description¶
The --set operation modifies the current generation of a profile so that it contains exactly the specified derivation, and nothing else.
Examples¶
The following updates a profile such that its current generation will contain just Firefox:
$ nix-env -p /nix/var/nix/profiles/browser --set firefox
OPERATION --SET-FLAG¶
Synopsis¶
nix-env --set-flag name value drvnames...
Description¶
The --set-flag 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 nix-env or the user environment build script:
Examples¶
To prevent the currently installed Firefox from being upgraded:
$ nix-env --set-flag keep true firefox
After this, nix-env -u will ignore Firefox.
To disable the currently installed Firefox, then install a new Firefox while the old remains part of the profile:
$ nix-env -q firefox-2.0.0.9 (the current one) $ 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/...-firefox-2.0.0.11/bin/firefox'
and `/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 `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 (the enabled one) firefox-2.0.0.9 (the disabled one)
To make files from binutils take precedence over files from gcc:
$ nix-env --set-flag priority 5 binutils $ nix-env --set-flag priority 10 gcc
OPERATION --QUERY¶
Synopsis¶
nix-env {--query | -q} [--installed
| --available | -a]
[{--status | -s}]
[{--attr-path | -P}] [--no-name]
[{--compare-versions | -c}] [--system]
[--drv-path] [--out-path] [--description]
[--meta]
[--xml] [--json]
[{--prebuilt-only | -b}]
[{--attr | -A} attribute-path]
names...
Description¶
The query operation displays information about either the store paths that are installed in the current generation of the active profile (--installed), or the derivations that are available for installation in the active Nix expression (--available). It only prints information about derivations whose symbolic name matches one of names.
The derivations are sorted by their name attributes.
Source selection¶
The following flags specify the set of things on which the query operates.
--installed
--available, -a
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 --no-name is specified.
--xml
--json
--prebuilt-only / -b
--status, -s
--attr-path, -P
--no-name
--compare-versions / -c
< version
= version
> version
- ?
--system
--drv-path
--out-path
--description
--meta
Examples¶
To show installed packages:
$ nix-env -q bison-1.875c docbook-xml-4.2 firefox-1.0.4 MPlayer-1.0pre7 ORBit2-2.8.3 ...
To show available packages:
$ nix-env -qa firefox-1.0.7 GConf-2.4.0.1 MPlayer-1.0pre7 ORBit2-2.8.3 ...
To show the status of available packages:
$ 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) ...
To show available packages in the Nix expression foo.nix:
$ nix-env -f ./foo.nix -qa foo-1.2.3
To compare installed versions to what’s available:
$ 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) ...
To show all packages with “zip” in the name:
$ nix-env -qa '.*zip.*' bzip2-1.0.6 gzip-1.6 zip-3.0 ...
To show all packages with “firefox” or “chromium” in the name:
$ 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 ...
To show all packages in the latest revision of the Nixpkgs repository:
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
OPERATION --SWITCH-PROFILE¶
Synopsis¶
nix-env {--switch-profile | -S} {path}
Description¶
This operation makes path the current profile for the user. That is, the symlink ~/.nix-profile is made to point to path.
Examples¶
$ nix-env -S ~/my-profile
OPERATION --LIST-GENERATIONS¶
Synopsis¶
nix-env --list-generations
Description¶
This operation print a list of all the currently existing generations for the active profile. These may be switched to using the --switch-generation operation. It also prints the creation date of the generation, and indicates the current generation.
Examples¶
$ 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)
OPERATION --DELETE-GENERATIONS¶
Synopsis¶
nix-env --delete-generations generations...
Description¶
This operation deletes the specified generations of the current profile. The generations can be a list of generation numbers, the special value old to delete all non-current generations, a value such as 30d 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 +5 to keep the last 5 generations ignoring any newer than current, e.g., if 30 is the current generation +5 will delete generation 25 and all older generations. Periodically deleting old generations is important to make garbage collection effective.
Examples¶
$ 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
OPERATION --SWITCH-GENERATION¶
Synopsis¶
nix-env {--switch-generation | -G} {generation}
Description¶
This operation makes generation number generation the current generation of the active profile. That is, if the profile is the path to the active profile, then the symlink profile is made to point to profile-generation-link, which is in turn a symlink to the actual user environment in the Nix store.
Switching will fail if the specified generation does not exist.
Examples¶
$ nix-env -G 42 switching from generation 50 to 42
OPERATION --ROLLBACK¶
Synopsis¶
nix-env --rollback
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 --list-generations and --switch-generation.
Examples¶
$ nix-env --rollback switching from generation 92 to 91 $ nix-env --rollback error: no generation older than the current (91) exists
ENVIRONMENT VARIABLES¶
NIX_PROFILE
IN_NIX_SHELL
NIX_PATH
/home/eelco/Dev:/etc/nixos
will cause Nix to look for paths relative to /home/eelco/Dev and /etc/nixos, in that order. It is also possible to match paths against a prefix. For example, the value
nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos
will cause Nix to search for <nixpkgs/path> in /home/eelco/Dev/nixpkgs-branch/path and /etc/nixos/nixpkgs/path.
If a path in the Nix search path starts with http:// or https://, it is interpreted as the URL of a tarball that will be downloaded and unpacked to a temporary location. The tarball must consist of a single top-level directory. For example, setting NIX_PATH to
tells Nix to download the latest revision in the Nixpkgs/NixOS 15.09 channel.
A following shorthand can be used to refer to the official channels:
nixpkgs=channel:nixos-15.09
The search path can be extended using the -I option, which takes precedence over NIX_PATH.
NIX_IGNORE_SYMLINK_STORE
Note that if you’re symlinking the Nix store so that you can put it on another file system than the root file system, on Linux you’re better off using bind mount points, e.g.,
$ mkdir /nix $ mount -o bind /mnt/otherdisk/nix /nix
Consult the mount(8) manual page for details.
NIX_STORE_DIR
NIX_DATA_DIR
NIX_LOG_DIR
NIX_STATE_DIR
NIX_CONF_DIR
TMPDIR
NIX_REMOTE
NIX_SHOW_STATS
NIX_COUNT_CALLS
GC_INITIAL_HEAP_SIZE
AUTHOR¶
Eelco Dolstra
COPYRIGHT¶
Copyright © 2004-2018 Eelco Dolstra
12/12/2020 | Nix 2.3.7 |