---
name: "nix3-profile"
section: "1"
platform: "linux"
package: "nix-bin"
version: "2.26.3+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/nix3-profile"
---

# nix3-profile(1)

manage Nix profiles

**Warning** \
 This program is **experimental** ⟨@docroot@/development/experimental-features.md#xp-feature-nix-command⟩ and its interface is subject to change.

## Name

`nix profile` - manage Nix profiles

## Synopsis

`nix profile` \[*option*…\] *subcommand*

where *subcommand* is one of the following:

- •

  `nix profile diff-closures` ⟨./nix3-profile-diff-closures.md⟩ - show the closure difference between each version of a profile

- •

  `nix profile history` ⟨./nix3-profile-history.md⟩ - show all versions of a profile

- •

  `nix profile install` ⟨./nix3-profile-install.md⟩ - install a package into a profile

- •

  `nix profile list` ⟨./nix3-profile-list.md⟩ - list installed packages

- •

  `nix profile remove` ⟨./nix3-profile-remove.md⟩ - remove packages from a profile

- •

  `nix profile rollback` ⟨./nix3-profile-rollback.md⟩ - roll back to the previous version or a specified version of a profile

- •

  `nix profile upgrade` ⟨./nix3-profile-upgrade.md⟩ - upgrade packages using their most recent flake

- •

  `nix profile wipe-history` ⟨./nix3-profile-wipe-history.md⟩ - delete non-current versions of a profile

## Description

`nix profile` allows you to create and manage *Nix profiles*. 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.

## Files

### Profiles

A directory that contains links to profiles managed by `nix-env` ⟨@docroot@/command-ref/nix-env.md⟩ and `nix profile` ⟨@docroot@/command-ref/new-cli/nix3-profile.md⟩\\c :

- •

  `$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` ⟨@docroot@/command-ref/files/manifest.nix.md⟩ used by `nix-env` ⟨@docroot@/command-ref/nix-env.md⟩\\c . - `manifest.json` ⟨@docroot@/command-ref/files/manifest.json.md⟩ used by `nix profile` ⟨@docroot@/command-ref/new-cli/nix3-profile.md⟩ (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` ⟨@docroot@/command-ref/conf-file.md#conf-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 ⟨@docroot@/installation/installing-binary.md⟩ sets this up by default, unless you enable `use-xdg-base-directories` ⟨@docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories⟩\\c .

### Profile compatibility

**Warning**

Once you have used `nix profile` ⟨@docroot@/command-ref/new-cli/nix3-profile.md⟩ you can no longer use `nix-env` ⟨@docroot@/command-ref/nix-env.md⟩ without first deleting `$XDG_STATE_HOME/nix/profiles/profile`

Once you installed a package with `nix profile` ⟨@docroot@/command-ref/new-cli/nix3-profile.md⟩\\c , you get the following error message when using `nix-env` ⟨@docroot@/command-ref/nix-env.md⟩\\c :

```
$ 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

### Logging-related options

- •

  `--debug` ⟨#opt-debug⟩

-

  Set the logging verbosity level to ‘debug’.

- •

  `--log-format` ⟨#opt-log-format⟩ *format*

-

  Set the format of log output; one of `raw`, `internal-json`, `bar` or `bar-with-logs`.

- •

  `--print-build-logs` ⟨#opt-print-build-logs⟩ / `-L`

-

  Print full build logs on standard error.

- •

  `--quiet` ⟨#opt-quiet⟩

-

  Decrease the logging verbosity level.

- •

  `--verbose` ⟨#opt-verbose⟩ / `-v`

-

  Increase the logging verbosity level.

### Miscellaneous global options

- •

  `--help` ⟨#opt-help⟩

-

  Show usage information.

- •

  `--offline` ⟨#opt-offline⟩

-

  Disable substituters and consider all previously downloaded files up-to-date.

- •

  `--option` ⟨#opt-option⟩ *name* *value*

-

  Set the Nix configuration setting *name* to *value* (overriding `nix.conf`).

- •

  `--refresh` ⟨#opt-refresh⟩

-

  Consider all previously downloaded files out-of-date.

- •

  `--version` ⟨#opt-version⟩

-

  Show version information.

  **Note**

  See `man nix.conf` ⟨@docroot@/command-ref/conf-file.md#command-line-flags⟩ for overriding configuration settings with command line flags.