Provided by: nix-bin_2.16.1+dfsg-3ubuntu1_amd64 
Name
nix-env - manipulate or query Nix user environments
Synopsis
nix-env operation [options] [arguments…] [--option name value] [--arg name value]
[--argstr name value] [{--file | -f} path] [{--profile | -p} path] [--system-filter
system] [--dry-run]
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.
The following operations are available:
• --install
• --upgrade
• --uninstall
• --set
• --set-flag
• --query
• --switch-profile
• --list-generations
• --delete-generations
• --switch-generation
• --rollback
These pages can be viewed offline:
• man nix-env-<operation>.
Example: man nix-env-install
• nix-env --help --<operation>
Example: nix-env --help --install
Selectors
Several commands, such as nix-env --query and nix-env --install, 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
Matches the package name firefox and any version.
• firefox-32.0
Matches the package name firefox and version 32.0.
• gtk\\+
Matches the package name gtk+. The + 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.
• .\*
Matches any package name. This is the default for most commands.
• '.*zip.*'
Matches any package name containing the string zip. Note the dots: '*zip*' does not
work, because in a regular expression, the character * is interpreted as a quantifier.
• '.*(firefox|chromium).*'
Matches any package name containing the strings firefox or chromium.
Files
nix-env operates on the following files.
Default Nix expression
The source for the default Nix expressions used by nix-env:
• ~/.nix-defexpr
• $XDG_STATE_HOME/nix/defexpr if use-xdg-base-directories is set to true.
It is loaded as follows:
• If the default expression is a file, it is loaded as a Nix expression.
• If the default expression is a directory containing a default.nix file, that default.nix
file is loaded as a Nix expression.
• If the default expression 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 attribute set, each expression under an attribute with the same
name as the original file or subdirectory. 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.
Then, the resulting expression is interpreted like this:
• If the expression is an attribute 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.
For example, if the default expression contains two files, foo.nix and bar.nix, then the
default Nix expression will be equivalent to
{
foo = import ~/.nix-defexpr/foo.nix;
bar = import ~/.nix-defexpr/bar.nix;
}
The file manifest.nix is always ignored.
The command nix-channel places a symlink to the user’s current channels profile in this
directory. This makes all subscribed channels available as attributes in the default
expression.
User channel link
A symlink that ensures that nix-env can find your channels:
• ~/.nix-defexpr/channels
• $XDG_STATE_HOME/defexpr/channels if use-xdg-base-directories is set to true.
This symlink points to:
• $XDG_STATE_HOME/profiles/channels for regular users
• $NIX_STATE_DIR/profiles/per-user/root/channels for root
In a multi-user installation, you may also have ~/.nix-defexpr/channels_root, which links
to the channels of the root user.nix-env: ../nix-env.md
Profiles
A directory that contains links to profiles managed by nix-env and nix profile:
• $XDG_STATE_HOME/nix/profiles for regular users
• $NIX_STATE_DIR/profiles/per-user/root if the user is root
A profile is a directory of symlinks to files in the Nix store.
Filesystem layout
Profiles are versioned as follows. When using a profile named path, path is a symlink to
path-N-link, where N is the version of the profile. In turn, path-N-link is a symlink to
a path in the Nix store. For example:
$ ls -l ~alice/.local/state/nix/profiles/profile*
lrwxrwxrwx 1 alice users 14 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile -> profile-7-link
lrwxrwxrwx 1 alice users 51 Oct 28 16:18 /home/alice/.local/state/nix/profiles/profile-5-link -> /nix/store/q69xad13ghpf7ir87h0b2gd28lafjj1j-profile
lrwxrwxrwx 1 alice users 51 Oct 29 13:20 /home/alice/.local/state/nix/profiles/profile-6-link -> /nix/store/6bvhpysd7vwz7k3b0pndn7ifi5xr32dg-profile
lrwxrwxrwx 1 alice users 51 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile-7-link -> /nix/store/mp0x6xnsg0b8qhswy6riqvimai4gm677-profile
Each of these symlinks is a root for the Nix garbage collector.
The contents of the store path corresponding to each version of the profile is a tree of
symlinks to the files of the installed packages, e.g.
$ ll -R ~eelco/.local/state/nix/profiles/profile-7-link/
/home/eelco/.local/state/nix/profiles/profile-7-link/:
total 20
dr-xr-xr-x 2 root root 4096 Jan 1 1970 bin
-r--r--r-- 2 root root 1402 Jan 1 1970 manifest.nix
dr-xr-xr-x 4 root root 4096 Jan 1 1970 share
/home/eelco/.local/state/nix/profiles/profile-7-link/bin:
total 20
lrwxrwxrwx 5 root root 79 Jan 1 1970 chromium -> /nix/store/ijm5k0zqisvkdwjkc77mb9qzb35xfi4m-chromium-86.0.4240.111/bin/chromium
lrwxrwxrwx 7 root root 87 Jan 1 1970 spotify -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/bin/spotify
lrwxrwxrwx 3 root root 79 Jan 1 1970 zoom-us -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/bin/zoom-us
/home/eelco/.local/state/nix/profiles/profile-7-link/share/applications:
total 12
lrwxrwxrwx 4 root root 120 Jan 1 1970 chromium-browser.desktop -> /nix/store/4cf803y4vzfm3gyk3vzhzb2327v0kl8a-chromium-unwrapped-86.0.4240.111/share/applications/chromium-browser.desktop
lrwxrwxrwx 7 root root 110 Jan 1 1970 spotify.desktop -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/share/applications/spotify.desktop
lrwxrwxrwx 3 root root 107 Jan 1 1970 us.zoom.Zoom.desktop -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/share/applications/us.zoom.Zoom.desktop
…
Each profile version contains a manifest file: - manifest.nix used by nix-env. -
manifest.json used by nix profile (experimental).
User profile link
A symbolic link to the user’s current profile:
• ~/.nix-profile
• $XDG_STATE_HOME/nix/profile if use-xdg-base-directories is set to true.
By default, this symlink points to:
• $XDG_STATE_HOME/nix/profiles/profile for regular users
• $NIX_STATE_DIR/profiles/per-user/root/profile for root
The PATH environment variable should include /bin subdirectory of the profile link (e.g.
~/.nix-profile/bin) for the user environment to be visible to the user. The installer
sets this up by default, unless you enable use-xdg-base-directories.
nix-env(1)