.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix3-profile" "1" ""
.RS
.PP
\fBWarning\fR 
.br
This program is
.UR @docroot@/development/experimental-features.md#xp-feature-nix-command
\fBexperimental\fR
.UE
and its interface is subject to change.
.RE
.SH Name
.LP
\f(CRnix profile\fR - manage Nix profiles
.SH Synopsis
.LP
\f(CRnix profile\fR [\fIoption\fR\[u2026]] \fIsubcommand\fR
.PP
where \fIsubcommand\fR is one of the following:
.IP "\(bu" 3
.UR ./nix3-profile-diff-closures.md
\f(CRnix profile diff-closures\fR
.UE
- show the closure difference between each version of a profile
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
.UR ./nix3-profile-history.md
\f(CRnix profile history\fR
.UE
- show all versions of a profile
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
.UR ./nix3-profile-install.md
\f(CRnix profile install\fR
.UE
- install a package into a profile
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
.UR ./nix3-profile-list.md
\f(CRnix profile list\fR
.UE
- list installed packages
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
.UR ./nix3-profile-remove.md
\f(CRnix profile remove\fR
.UE
- remove packages from a profile
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
.UR ./nix3-profile-rollback.md
\f(CRnix profile rollback\fR
.UE
- roll back to the previous version or a specified version of a profile
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
.UR ./nix3-profile-upgrade.md
\f(CRnix profile upgrade\fR
.UE
- upgrade packages using their most recent flake
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
.UR ./nix3-profile-wipe-history.md
\f(CRnix profile wipe-history\fR
.UE
- delete non-current versions of a profile
.SH Description
.LP
\f(CRnix profile\fR allows you to create and manage \fINix profiles\fR. A Nix
profile is a set of packages that can be installed and upgraded
independently from each other. Nix profiles are versioned, allowing
them to be rolled back easily.
.SH Files
.SS
Profiles
.LP
A directory that contains links to profiles managed by \c
.UR @docroot@/command-ref/nix-env.md
\f(CRnix-env\fR
.UE
and \c
.UR @docroot@/command-ref/new-cli/nix3-profile.md
\f(CRnix profile\fR
.UE \c
:
.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:
- \c
.UR @docroot@/command-ref/files/manifest.nix.md
\f(CRmanifest.nix\fR
.UE
used by \c
.UR @docroot@/command-ref/nix-env.md
\f(CRnix-env\fR
.UE \c
\&.
- \c
.UR @docroot@/command-ref/files/manifest.json.md
\f(CRmanifest.json\fR
.UE
used by \c
.UR @docroot@/command-ref/new-cli/nix3-profile.md
\f(CRnix profile\fR
.UE
(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 \c
.UR @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
\f(CRuse-xdg-base-directories\fR
.UE
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 \c
.UR @docroot@/installation/installing-binary.md
installer
.UE
sets this up by default, unless you enable \c
.UR @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
\f(CRuse-xdg-base-directories\fR
.UE \c
\&.
.SS
Profile compatibility
.RS
.LP
\fBWarning\fR
.PP
Once you have used \c
.UR @docroot@/command-ref/new-cli/nix3-profile.md
\f(CRnix profile\fR
.UE
you can no longer use \c
.UR @docroot@/command-ref/nix-env.md
\f(CRnix-env\fR
.UE
without first deleting \f(CR$XDG_STATE_HOME/nix/profiles/profile\fR
.RE
.PP
Once you installed a package with \c
.UR @docroot@/command-ref/new-cli/nix3-profile.md
\f(CRnix profile\fR
.UE \c
, you get the following error message when using \c
.UR @docroot@/command-ref/nix-env.md
\f(CRnix-env\fR
.UE \c
:
.LP
.EX
$ nix-env -f '<nixpkgs>' -iA 'hello'
error: nix-env
profile '/home/alice/.local/state/nix/profiles/profile' is incompatible with 'nix-env'; please use 'nix profile' instead
.EE
.PP
To migrate back to \f(CRnix-env\fR you can delete your current profile:
.RS
.PP
\fBWarning\fR
.PP
This will delete packages that have been installed before, so you may want to back up this information before running the command.
.RE
.LP
.EX
 $ rm -rf \(dq${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile\(dq
.EE
.SH Options
.SS
Logging-related options
.IP "\(bu" 3
.UR #opt-debug
\f(CR--debug\fR
.UE
.IP
Set the logging verbosity level to \(oqdebug\(cq.
.IP "\(bu" 3
.UR #opt-log-format
\f(CR--log-format\fR
.UE
\fIformat\fR
.IP
Set the format of log output; one of \f(CRraw\fR, \f(CRinternal-json\fR, \f(CRbar\fR or \f(CRbar-with-logs\fR.
.IP "\(bu" 3
.UR #opt-print-build-logs
\f(CR--print-build-logs\fR
.UE
/ \f(CR-L\fR
.IP
Print full build logs on standard error.
.IP "\(bu" 3
.UR #opt-quiet
\f(CR--quiet\fR
.UE
.IP
Decrease the logging verbosity level.
.IP "\(bu" 3
.UR #opt-verbose
\f(CR--verbose\fR
.UE
/ \f(CR-v\fR
.IP
Increase the logging verbosity level.
.SS
Miscellaneous global options
.IP "\(bu" 3
.UR #opt-help
\f(CR--help\fR
.UE
.IP
Show usage information.
.IP "\(bu" 3
.UR #opt-offline
\f(CR--offline\fR
.UE
.IP
Disable substituters and consider all previously downloaded files up-to-date.
.IP "\(bu" 3
.UR #opt-option
\f(CR--option\fR
.UE
\fIname\fR \fIvalue\fR
.IP
Set the Nix configuration setting \fIname\fR to \fIvalue\fR (overriding \f(CRnix.conf\fR).
.IP "\(bu" 3
.UR #opt-refresh
\f(CR--refresh\fR
.UE
.IP
Consider all previously downloaded files out-of-date.
.IP "\(bu" 3
.UR #opt-version
\f(CR--version\fR
.UE
.IP
Show version information.
.RS
.LP
\fBNote\fR
.PP
See \c
.UR @docroot@/command-ref/conf-file.md#command-line-flags
\f(CRman nix.conf\fR
.UE
for overriding configuration settings with command line flags.
.RE