.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix-env" "1" ""
.SH Name
.LP
\f(CRnix-env\fR - manipulate or query Nix user environments
.SH Synopsis
.LP
\f(CRnix-env\fR \fIoperation\fR [\fIoptions\fR] [\fIarguments…\fR]
[\f(CR--option\fR \fIname\fR \fIvalue\fR]
[\f(CR--arg\fR \fIname\fR \fIvalue\fR]
[\f(CR--argstr\fR \fIname\fR \fIvalue\fR]
[{\f(CR--file\fR | \f(CR-f\fR} \fIpath\fR]
[{\f(CR--profile\fR | \f(CR-p\fR} \fIpath\fR]
[\f(CR--system-filter\fR \fIsystem\fR]
[\f(CR--dry-run\fR]
.SH Description
.LP
The command \f(CRnix-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
\f(CRnix-env\fR takes exactly one \fIoperation\fR flag which indicates the
subcommand to be performed. The following operations are available:
.IP "\(bu" 3
\fB\f(CR--install\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--upgrade\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--uninstall\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--set\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--set-flag\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--query\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--switch-profile\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--list-generations\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--delete-generations\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--switch-generation\fR\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CR--rollback\fR\fR
.LP
These pages can be viewed offline:
.IP "\(bu" 3
\f(CRman nix-env-<operation>\fR.
.IP
Example: \f(CRman nix-env-install\fR
.IP "\(bu" 3
\f(CRnix-env --help --<operation>\fR
.IP
Example: \f(CRnix-env --help --install\fR
.SH Package sources
.LP
\f(CRnix-env\fR can obtain packages from multiple sources:
.IP "\(bu" 3
An attribute set of derivations from:
.RS
.IP "\(bu" 3
The \fBdefault Nix expression\fR (by default)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
A Nix file, specified via \f(CR--file\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
A \fBprofile\fR, specified via \f(CR--from-profile\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
A Nix expression that is a function which takes default expression as argument, specified via \f(CR--from-expression\fR
.RE
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
A \fBstore path\fR
.SH Selectors
.LP
Several operations, such as \fB\f(CRnix-env --query\fR\fR and \fB\f(CRnix-env --install\fR\fR, take a list of \fIarguments\fR that specify the packages on which to operate.
.PP
Packages are identified based on a \f(CRname\fR part and a \f(CRversion\fR part of a \fBsymbolic derivation name\fR:
.IP "\(bu" 3
\f(CRname\fR: Everything up to but not including the first dash (\f(CR-\fR) that is \fInot\fR followed by a letter.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRversion\fR: The rest, excluding the separating dash.
.RS
.LP
\fBExample\fR
.PP
\f(CRnix-env\fR parses the symbolic derivation name \f(CRapache-httpd-2.0.48\fR as:
.LP
.EX
{
  \(dqname\(dq: \(dqapache-httpd\(dq,
  \(dqversion\(dq: \(dq2.0.48\(dq
}
.EE
.PP
\fBExample\fR
.PP
\f(CRnix-env\fR parses the symbolic derivation name \f(CRfirefox.*\fR as:
.LP
.EX
{
  \(dqname\(dq: \(dqfirefox.*\(dq,
  \(dqversion\(dq: \(dq\(dq
}
.EE
.RE
.PP
The \f(CRname\fR parts of the \fIarguments\fR to \f(CRnix-env\fR are treated as extended regular expressions and matched against the \f(CRname\fR parts of derivation names in the package source.
The match is case-sensitive.
The regular expression can optionally be followed by a dash (\f(CR-\fR) and a version number; if omitted, any version of the package will match.
For details on regular expressions, see \fB\fBregex\fR(7)\fR.
.RS
.PP
\fBExample\fR
.PP
Common patterns for finding package names with \f(CRnix-env\fR:
.IP "\(bu" 3
\f(CRfirefox\fR
.IP
Matches the package name \f(CRfirefox\fR and any version.
.IP "\(bu" 3
\f(CRfirefox-32.0\fR
.IP
Matches the package name \f(CRfirefox\fR and version \f(CR32.0\fR.
.IP "\(bu" 3
\f(CRgtk\e\e+\fR
.IP
Matches the package name \f(CRgtk+\fR.
The \f(CR+\fR character must be escaped using a backslash (\f(CR\e\fR) 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" 3
\f(CR.\e*\fR
.IP
Matches any package name.
This is the default for most commands.
.IP "\(bu" 3
\f(CR'.*zip.*'\fR
.IP
Matches any package name containing the string \f(CRzip\fR.
Note the dots: \f(CR'*zip*'\fR does not work, because in a regular expression, the character \f(CR*\fR is interpreted as a quantifier.
.IP "\(bu" 3
\f(CR'.*(firefox|chromium).*'\fR
.IP
Matches any package name containing the strings \f(CRfirefox\fR or \f(CRchromium\fR.
.RE
.SH Files
.LP
\f(CRnix-env\fR operates on the following files.
.SS
Default Nix expression
.LP
The source for the default \fBNix expressions\fR used by \fB\f(CRnix-env\fR\fR:
.IP "\(bu" 3
\f(CR\(ti/.nix-defexpr\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR$XDG_STATE_HOME/nix/defexpr\fR if \fB\f(CRuse-xdg-base-directories\fR\fR is set to \f(CRtrue\fR.
.LP
It is loaded as follows:
.IP "\(bu" 3
If the default expression is a file, it is loaded as a Nix expression.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
If the default expression is a directory containing a \f(CRdefault.nix\fR file, that \f(CRdefault.nix\fR file is loaded as a Nix expression.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
If the default expression is a directory without a \f(CRdefault.nix\fR 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 \f(CRdefault.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.
.LP
Then, the resulting expression is interpreted like this:
.IP "\(bu" 3
If the expression is an attribute set, it is used as the default Nix expression.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
If the expression is a function, an empty set is passed as argument and the return value is used as the default Nix expression.
.LP
For example, if the default expression contains two files, \f(CRfoo.nix\fR and \f(CRbar.nix\fR, then the default Nix expression will be equivalent to
.LP
.EX
{
  foo = import \(ti/.nix-defexpr/foo.nix;
  bar = import \(ti/.nix-defexpr/bar.nix;
}
.EE
.PP
The file \fB\f(CRmanifest.nix\fR\fR is always ignored.
.PP
The command \fB\f(CRnix-channel\fR\fR places a symlink to the user\(cqs current \fBchannels profile\fR in this directory.
This makes all subscribed channels available as attributes in the default expression.
.SS
User channel link
.LP
A symlink that ensures that \fB\f(CRnix-env\fR\fR can find your channels:
.IP "\(bu" 3
\f(CR\(ti/.nix-defexpr/channels\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR$XDG_STATE_HOME/defexpr/channels\fR if \fB\f(CRuse-xdg-base-directories\fR\fR is set to \f(CRtrue\fR.
.LP
This symlink points to:
.IP "\(bu" 3
\f(CR$XDG_STATE_HOME/profiles/channels\fR for regular users
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR$NIX_STATE_DIR/profiles/per-user/root/channels\fR for \f(CRroot\fR
.LP
In a multi-user installation, you may also have \f(CR\(ti/.nix-defexpr/channels_root\fR, which links to the channels of the root user.\fB\f(CRnix-env\fR\fR: ../nix-env.md
.SS
Profiles
.LP
A directory that contains links to profiles managed by \fB\f(CRnix-env\fR\fR and \fB\f(CRnix profile\fR\fR:
.IP "\(bu" 3
\f(CR$XDG_STATE_HOME/nix/profiles\fR for regular users
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR$NIX_STATE_DIR/profiles/per-user/root\fR if the user is \f(CRroot\fR
.LP
A profile is a directory of symlinks to files in the Nix store.
.SS
Filesystem layout
.LP
Profiles are versioned as follows. When using a profile named \fIpath\fR, \fIpath\fR is a symlink to \fIpath\fR\f(CR-\fR\fIN\fR\f(CR-link\fR, where \fIN\fR is the version of the profile.
In turn, \fIpath\fR\f(CR-\fR\fIN\fR\f(CR-link\fR is a symlink to a path in the Nix store.
For example:
.LP
.EX
$ ls -l \(tialice/.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
.EE
.PP
Each of these symlinks is a root for the Nix garbage collector.
.PP
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.
.LP
.EX
$ ll -R \(tieelco/.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

…
.EE
.PP
Each profile version contains a manifest file:
- \fB\f(CRmanifest.nix\fR\fR used by \fB\f(CRnix-env\fR\fR.
- \fB\f(CRmanifest.json\fR\fR used by \fB\f(CRnix profile\fR\fR (experimental).
.SS
User profile link
.LP
A symbolic link to the user\(cqs current profile:
.IP "\(bu" 3
\f(CR\(ti/.nix-profile\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR$XDG_STATE_HOME/nix/profile\fR if \fB\f(CRuse-xdg-base-directories\fR\fR is set to \f(CRtrue\fR.
.LP
By default, this symlink points to:
.IP "\(bu" 3
\f(CR$XDG_STATE_HOME/nix/profiles/profile\fR for regular users
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR$NIX_STATE_DIR/profiles/per-user/root/profile\fR for \f(CRroot\fR
.LP
The \f(CRPATH\fR environment variable should include \f(CR/bin\fR subdirectory of the profile link (e.g. \f(CR\(ti/.nix-profile/bin\fR) for the user environment to be visible to the user.
The \fBinstaller\fR sets this up by default, unless you enable \fB\f(CRuse-xdg-base-directories\fR\fR.