nix3-profile(1)

📦
version 2.35.3 · 13 versions
, in fedora 44

💖 nix3-profile(1) 💖

ok so this page lives in the General Commands Manual bestie, and before we even start:

⚠️ Warning — this program is experimental and its interface is subject to change. like, don't build your whole personality on it staying the same, k? 💀

✨ Name ✨

nix profile — manage Nix profiles 🫶

🌸 Synopsis 🌸

nix profile [option…] subcommand

and subcommand is one of these lil icons 👑:

  • nix profile add — add a package to a profile
  • nix profile diff-closures — show the closure difference between each version of a profile
  • nix profile history — show all versions of a profile
  • nix profile list — list packages in the profile
  • nix profile remove — remove packages from a profile
  • nix profile rollback — roll back to the previous version or a specified version of a profile
  • nix profile upgrade — upgrade packages using their most recent flake
  • nix profile wipe-history — delete non-current versions of a profile

🦋 Description 🦋

nix profile lets you create and manage Nix profiles. a Nix profile is basically a lil squad of packages that can be installed and upgraded independently from each other. and the best part? Nix profiles are versioned, so rolling back is easy-peasy. no cap. ✨

🎀 Files 🎀

💜 Profiles

so, 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. that's the whole vibe.

🌈 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. and then path-N-link is a symlink to a path in the Nix store. like:

$ 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 one of these symlinks is a root for the Nix garbage collector. keep that in mind, it's important iykyk 🧚

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/cyxny9d1zjb9l9103fr6j6kavp3bqjxf-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/sqzyx2l85i6j2a77pnyvglh3bvzwmjjp-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, and there are two of them:

  • manifest.nix used by nix-env.
  • manifest.json used by nix profile (experimental).

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 the /bin subdirectory of the profile link (e.g. ~/.nix-profile/bin) so the user environment is actually visible to the user. the installer sets this up by default, unless you enable use-xdg-base-directories. 💅

⭐ Profile compatibility

⚠️ Warning once you have used nix profile you can no longer use nix-env without first deleting $XDG_STATE_HOME/nix/profiles/profile

once you installed a package with nix profile, you get this error message when using nix-env:

$ 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

to migrate back to nix-env you can delete your current profile:

⚠️ Warning this will delete packages that have been installed before, so you may want to back up this information before running the command. 😭
$ rm -rf "${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile"

👑 Options 👑

  • --debug — set the logging verbosity level to 'debug'.
  • --log-format format — set the format of log output; one of raw, internal-json, bar or bar-with-logs.
  • --print-build-logs / -L — print full build logs on standard error.
  • --quiet — decrease the logging verbosity level.
  • --verbose / -v — increase the logging verbosity level.

💖 Miscellaneous global options

  • --help — show usage information.
  • --offline — disable substituters and consider all previously downloaded files up-to-date.
  • --option name value — set the Nix configuration setting name to value (overriding nix.conf).
  • --refresh — consider all previously downloaded files out-of-date.
  • --version — show version information.
📝 Note see man nix.conf for overriding configuration settings with command line flags.

and that's the whole page bestie, slay 💅✨ this was nix3-profile(1) from the General Commands Manual, showing up in your terminal with all the group-chat energy it deserves. go manage those profiles, you got this 🫶🌈👑

📦 where this page comes from