nix-profiles(5)

📦
version 2.35.3 · 8 versions
, in fedora 44

💖 nix-profiles(5) — okay so let's talk profiles ✨

Hi bestie!! Welcome to nix-profiles(5), straight out of the File Formats Manual 🎀. This is the page where we spill all the tea about how Nix lays out your profiles on disk — the symlinks, the versioning, the whole filesystem vibe. Buckle up, it's giving ✨filesystem lore✨.

🌸 Profiles

A profile situation is a directory that holds links to profiles managed by nix-env and nix profile. Here's where that directory lives:

  • $XDG_STATE_HOME/nix/profiles for regular users 🫶
  • $NIX_STATE_DIR/profiles/per-user/root if the user is root 👑

And like… what even is a profile? A profile is a directory of symlinks to files in the Nix store. That's it. That's the whole thing. Symlinks all the way down, no cap 💅.

🦋 Filesystem layout

So profiles are versioned, and here's how that works. When you're using a profile named path, then path is a symlink to path-N-link, where N is the version of the profile. And then — plot twist — path-N-link is itself a symlink to a path in the Nix store. Nested symlinks, main character energy fr fr.

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. Say it with me: gc root, gc root, gc root 🗣️. That's why your stuff doesn't get yeeted ✨.

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

Look at all those little bin entries 🥹 they're so cute. And then the page just goes:

…

💀 mood.

Each profile version contains a manifest file:

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

This is a symbolic link to the user's current profile — the one you're actually living in rn. It's at:

  • ~/.nix-profile
  • $XDG_STATE_HOME/nix/profile if use-xdg-base-directories is set to true.

And 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 👑
ok so super important bestie: for your user environment to be visible to the user, the PATH environment variable should include the /bin subdirectory of the profile link (e.g. ~/.nix-profile/bin). The installer sets this up by default ✨ — unless you enable use-xdg-base-directories. Then it's on you, love 🫶

and that's the whole page!! you officially understand profile layout, symlink versioning, gc roots, and manifests. iconic behavior, truly. 💖

sign-off time 🎀 — this was nix-profiles(5) from the File Formats Manual (the Nix manual, experimental-flavored), and the footer on this one just says nix-profiles(5) again, no date, no version, because nix keeps us guessing 😌💅

📦 where this page comes from