NIX-ENV-SWITCH-PROFILE(1)

📦
version 2.35.3 · 10 versions
, in fedora 44

✨ nix-env --switch-profile(1) ✨

bestie wake up, we're switching PROFILES 💅

okay so this page lives in the General Commands Manual and it's literally about one (1) job: making a different profile Your Profile. no cap. let's get into it 🦋

🌸 Name 🌸

nix-env --switch-profile — set user environment to given profile

(yes queen, that's the whole vibe: you point, it switches 💖)

🎀 Synopsis 🎀

nix-env {--switch-profile | -S} path

that's it. that's the summoning circle. you got --switch-profile OR you got -S (the cute lil short version 💅), and then a path. iconic honestly.

🫶 Description 🫶

okay so here's the tea, and it's actually simple for once:

This operation makes path the current profile for the user. that's not a metaphor bestie, it's mechanical:

the symlink ~/.nix-profile is made to point to path.

that's the whole thing. ~/.nix-profile ➡️ wherever you told it to point. no drama, no build, no generations getting shuffled around behind your back. just a symlink doing a lil glow-up ✨

💖 Options 💖

heads up girlypop: the following options are allowed for all nix-env operations, but they may not always have an effect. so yes they're legal here, but don't come crying to me if they're just standing there looking pretty 💀
  • --file, -f path — Specifies the Nix expression (we'll call it the active Nix expression from here on) that the --install, --upgrade, and --query --available operations use to obtain derivations. The default is ~/.nix-defexpr.
and here's the plot twist 🌀: if the argument starts with http:// or https://, it gets interpreted as the URL of a tarball that will be downloaded and unpacked to a temporary location. That tarball must include a single top-level directory containing at least a file named default.nix. yes, must. single top-level dir. don't test it 🙈
  • --profile, -p path — Specifies the profile to be used by those operations that operate on a profile (designated below as the active profile). A profile is a sequence of user environments called generations, one of which is the current generation.
iykyk — generations are the whole point. it's a lil lineup of user environments and exactly one of them gets to be the moment 👑
  • --dry-run — For the --install, --upgrade, --uninstall, --switch-generation, --delete-generations and --rollback operations, this flag will cause nix-env to print what would be done if this flag had not been specified, without actually doing it.
it's giving "manifesting but not committing" 🧚
also: --dry-run prints out which paths will be substituted (i.e., downloaded) and which paths will be built from source (because no substitute is available). so you get the full receipts before anything actually happens 📋
  • --system-filter system — By default, operations such as --query --available show derivations matching any platform. This option allows you to use derivations for the specified platform system.
narrow that vibe check down to one platform bestie 🎯

that's part 1, and there's more coming — don't touch that dial 💖

✨ Common Options ✨

okay bestie, listen up 💅 — most Nix commands take all of these, so once you know them you basically know everything. no cap.

  • --help — spits out a lil summary of the command syntax and then dips. that's it, that's the whole job. 👋
  • --version — prints the Nix version number on standard output and exits. iconic behavior honestly.
  • --verbose / -v — cranks UP the level of verbosity for diagnostic messages printed on standard error. here's the tea: for each Nix operation, the stuff on standard output is well-defined, and any diagnostic info goes to standard error, never standard output. you can pass this option repeatedly (yes, stack it, it's giving layers 💅). currently these verbosity levels exist:
    • 0 “Errors only” — only prints messages explaining why the Nix invocation failed. it's giving minimalism.
    • 1 “Informational” — prints useful messages about what Nix is doing. this is the default, bestie.
    • 2 “Talkative” — more informational messages. it's chatty now.
    • 3 “Chatty” — even MORE informational messages.
    • 4 “Debug” — prints debug information.
    • 5 “Vomit” — prints vast amounts of debug information. literally 💀 absolute deluge.
  • --quiet — turns the verbosity back DOWN for diagnostic messages on standard error. it's the inverse option to -v / --verbose, they're enemies to lovers fr. you can also pass this one repeatedly, so go check that verbosity levels list up above, it's the same scale. 🫶
  • --log-format format — use this to change the output of the log format, where format is one of:
    • raw — the raw format, as outputted by nix-build.
    • internal-json — outputs the logs in a structured manner.
⚠️ Warning — while the schema itself is relatively stable, the format of the error-messages (namely of the msg-field) can change between releases. so like, don't hard-depend on it bestie 😭
  • bar — only display a progress bar during the builds. aesthetic.
  • bar-with-logs — displays the raw logs, with the progress bar at the bottom.
  • --no-build-output / -Q — by default, output written by builders to standard output and standard error gets echoed to the Nix command's standard error. this option suppresses that. note that the builder's standard output and error are always written to a log file in prefix/nix/var/log/nix.
  • --max-jobs / -j number — sets the max number of build jobs Nix will do in parallel to the number you give it. you can say auto to use the number of CPUs in the system 🖥️. the default is set by the max-jobs configuration setting, which itself defaults to 1. a higher value is useful on SMP systems, or to exploit I/O latency. setting it to 0 disallows building on the local machine — handy when you want builds to happen only on remote builders. go off, distributed queen 👑
  • --cores — sets the value of the NIX_BUILD_CORES environment variable in the invocation of builders. builders can use this variable at their discretion to control the maximum amount of parallelism. for instance, in Nixpkgs, if the derivation attribute enableParallelBuilding is set to true, the builder passes the -jN flag to GNU Make. it defaults to the value of the cores configuration setting, if set, or 1 otherwise. the value 0 means the builder should use all available CPU cores in the system 🔥.
  • --max-silent-time — sets the max number of seconds a builder can go without producing any data on standard output or standard error. the default is set by the max-silent-time configuration setting. 0 means no time-out. silence really is golden i guess 🙈
  • --timeout — sets the max number of seconds a builder can run. the default is set by the timeout configuration setting. 0 means no timeout.
  • --keep-going / -k — keep going in case of failed builds, to the greatest extent possible. that means: if building an input of some derivation fails, Nix will still build the other inputs, but not the derivation itself. without this option, Nix stops if any build fails (except for builds of substitutes), possibly killing builds in progress (in case of parallel or distributed builds). resilient queen energy 💅
  • --keep-failed / -K — says that in case of a build failure, the temporary directory (usually in /tmp) where the build takes place should not be deleted. the path of the build directory is printed as an informational message. very demure, very "come back and inspect me later". 🎀
  • --fallback — whenever Nix tries to build a derivation for which substitutes are known for each output path, but realising the output paths through the substitutes fails, fall back on building the derivation. the most common scenario where this slays: you've registered substitutes to do binary distribution from, say, a network repository 🌐. if the repository is down, the realisation of the derivation will fail. with this option, Nix will build the derivation instead. so installation from binaries falls back on installation from source. it's not the default, because it's generally not desirable for a transient failure in obtaining the substitutes to lead to a full build from source (with all the related resource consumption 😭). choose wisely bestie.
  • --readonly-mode — when this is on, no attempt is made to open the Nix database. most Nix operations genuinely NEED database access, so those operations will just fail 💀. it's giving "i'm just window shopping".
  • --arg name value — this option is accepted by nix-env, nix-instantiate, nix-shell and nix-build. when evaluating Nix expressions, the expression evaluator will automatically try to call functions that it encounters. it can automatically call functions for which every argument has a default value (e.g., { argName ? defaultValue }: ...).

with --arg, you can also call functions that have arguments without a default value (or override a default value). that is, if the evaluator encounters a function with an argument named name, it will call it with value value.

for instance, the top-level default.nix in Nixpkgs is actually a function:

{ # The system (e.g., `i686-linux') for which to build the packages.
system ? builtins.currentSystem
...
}: ...

so if you call this Nix expression (e.g., when you do nix-env --install --attr pkgname), the function will be called automatically using the value builtins.currentSystem for the system argument. you can override this using --arg, e.g., nix-env --install --attr pkgname --arg system "i686-freebsd". (note that since the argument is a Nix string literal, you have to escape the quotes.) 🐚

  • --arg-from-file name path — pass the contents of file path as the argument name to Nix functions. 📄
  • --arg-from-stdin name — pass the contents of stdin as the argument name to Nix functions. 🌊
  • --argstr name value — this is like --arg, only the value is not a Nix expression but a string. so instead of --arg system "i686-linux" (the outer quotes are to keep the shell happy) you can just say --argstr system i686-linux. so much easier, no thoughts head empty 🧚
  • --attr / -A attrPath — select an attribute from the top-level Nix expression being evaluated. (nix-env, nix-instantiate, nix-build and nix-shell only.) the attribute path attrPath is a sequence of attribute names separated by dots. for instance, given a top-level Nix expression e, the attribute path xorg.xorgserver would cause the expression e.xorg.xorgserver to be used. see nix-env --install for some concrete examples.

in addition to attribute names, you can also specify array indices 👀. for instance, the attribute path foo.3.bar selects the bar attribute of the fourth element of the array in the foo attribute of the top-level expression. (yes, index 3 = fourth element. we live in a society.)

  • --eval-store store-url — the URL to the Nix store to use for evaluation, i.e. where to store derivations (.drv files) and inputs referenced by them. 📦
  • --expr / -E — interpret the command line arguments as a list of Nix expressions to be parsed and evaluated, rather than as a list of file names of Nix expressions. (nix-instantiate, nix-build and nix-shell only.)

for nix-shell, this option is commonly used to give you a shell in which you can build the packages returned by the expression. if you want to get a shell which contain the built packages ready for use, give your expression to the nix-shell --packages convenience flag instead. bestie pls use the right flag i'm begging 😭

  • -I / --include path — add an entry to the list of search paths used to resolve lookup paths. this option may be given multiple times. paths added through -I take precedence over the nix-path configuration setting and the NIX_PATH environment variable. seniority matters 💅
  • --impure — allow access to mutable paths and repositories. chaotic. love that for us 🌈
  • --option name value — set the Nix configuration option name to value. this overrides settings in the Nix configuration file (see nix.conf5). 💖
  • --repair — fix corrupted or missing store paths by redownloading or rebuilding them. note that this is slow 😭 because it requires computing a cryptographic hash of the contents of every path in the closure of the build. also note the warning under nix-store --repair-path.
Note — see man nix.conf for overriding configuration settings with command line flags.

🌸 Environment variables 🌸

  • NIX_PROFILE — location of the Nix profile. defaults to the target of the symlink ~/.nix-profile, if it exists, or /nix/var/nix/profiles/default otherwise. so that's where your profile vibes live, bestie 🏠✨

🌈 Common Environment Variables 🌈

okay bestie, so most Nix commands read these little environment variables, and honestly they control EVERYTHING about how Nix behaves. buckle up, this is a long one 🎀

⚙️ Configuration environment variables

these ones decide how Nix finds and loads its config. the config file docs have the full deets if you want to go deeper 💅

  • NIX_CONF_DIR — overrides where the system configuration directory lives.
  • NIX_USER_CONF_FILES — overrides where the user configuration files live.
  • NIX_CONFIG — lets you drop configuration settings inline, no file needed. iconic.

🗄️ Store setting environment variables

  • NIX_IGNORE_SYMLINK_STORE — so normally, the Nix store directory (usually /nix/store) is not allowed to contain any symlink components. this is on purpose, to stop "impure" builds. the tea: builders sometimes "canonicalise" paths by resolving every symlink component, so builds on different machines (where /nix/store points somewhere different) could give you different results. usually that's fine, EXCEPT when builds get deployed to machines where /nix/store resolves differently. if you're 100% sure that's not your situation, you can set NIX_IGNORE_SYMLINK_STORE to 1. no cap, be sure.
heads up: if you're symlinking the Nix store just to put it on a different file system than root, on Linux you're way better off using bind mount points, like this:
$ mkdir /nix
$ mount -o bind /mnt/otherdisk/nix /nix

Consult the mount(8) manual page for details. 🫶

  • NIX_STORE_DIR — overrides where the Nix store is. On Unix the default is /nix/store, set at compile time by the libstore:store-dir build option. On Windows there's no compile-time setting at all; the default is %PROGRAMDATA%\nix\store, figured out at runtime using the %PROGRAMDATA% Known Folder.

See the Store Types chapter — each store has a store setting that links back to this as its default.

  • NIX_LOG_DIR — overrides where the Nix log directory is. On Unix the default is /nix/var/log/nix, set at compile time by the log-dir build option. On Windows, no compile-time setting; the default is %PROGRAMDATA%\nix\log, determined at runtime using the %PROGRAMDATA% Known Folder.

The Local Store, Local Daemon Store, and Experimental SSH Store with filesystem mounted all have per-store settings that override this.

  • NIX_STATE_DIR — overrides where the Nix state directory is. On Unix the default is ${localstatedir}/nix, where localstatedir is a compile-time build option that defaults to /nix/var. On Windows, no compile-time setting; the default is %PROGRAMDATA%\nix\state, determined at runtime using the %PROGRAMDATA% Known Folder.

Same deal: the Local Store, Local Daemon Store, and Experimental SSH Store with filesystem mounted have per-store settings that override this.

  • NIX_DAEMON_SOCKET_PATH — overrides the path to the Unix domain socket used to talk to the Nix daemon. defaults to daemon-socket/socket inside the state directory (peep NIX_STATE_DIR). see the Local Daemon Store documentation for how the socket path actually gets resolved 👑
  • TMPDIR — use this directory for temporary files. that includes temporary build directories, which can eat up a LOT of disk space, so pick wisely. default is /tmp.
  • NIX_REMOTE — overrides the store setting.

🧠 Nix language evaluator settings

  • NIX_SHOW_STATS — set it to 1 and Nix prints out some evaluation statistics, like how many values got allocated. fun little numbers ✨
  • NIX_COUNT_CALLS — set it to 1 and Nix prints how often functions were called while evaluating Nix expressions. super useful for profiling your Nix expressions.
  • GC_INITIAL_HEAP_SIZE — if Nix was configured to use the Boehm garbage collector, this sets the initial heap size in bytes. defaults to 384 MiB. setting it low reduces memory consumption but makes stuff run longer because garbage collection overhead goes up. it's giving tradeoff 💀
  • NIX_PATH — a colon-separated list of search path entries, used to resolve lookup paths.

This environment variable overrides the value of the nix-path configuration setting.

You can extend it with the -I option.

Example

$ export NIX_PATH=/home/eelco/Dev:nixos-config=/etc/nixos

If NIX_PATH is set to an empty string, resolving search paths will always fail.

Example

$ NIX_PATH= nix-instantiate --eval '<nixpkgs>'
error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)

🏠 User Directories

Nix supports per-user configuration, state, and cache directories, which is very main character of it. these environment variables override where those directories live:

  • user configuration directory (anchor #user-conf-dir): NIX_CONFIG_HOME (anchor #env-NIXCONFIGHOME)
  • user state directory: NIX_STATE_HOME (anchor #env-NIXSTATEHOME)
  • user cache directory: NIX_CACHE_HOME (anchor #env-NIXCACHEHOME)

When these aren't set, the defaults depend on the platform:

  • On Unix, the XDG base directories: $XDG_CONFIG_HOME/nix, $XDG_STATE_HOME/nix, $XDG_CACHE_HOME/nix
  • On Windows, the Windows Known Folders: %APPDATA%\nix\config, %LOCALAPPDATA%\nix\state, %LOCALAPPDATA%\nix\cache

For backwards compatibility, legacy Nix commands (like nix-env, nix-channel) use dotfiles in $HOME instead of these directories — unless use-xdg-base-directories is enabled. The new Nix commands (experimental) use the proper directories by default. glow up 🦋

When use-xdg-base-directories is enabled, the configuration directory gets resolved like this:

  1. $NIX_CONFIG_HOME, if it is defined
  2. Otherwise, the platform default (e.g. $XDG_CONFIG_HOME/nix on Unix)

Same logic for the state and cache directories. periodt.

🎲 Miscellaneous environment variables

  • IN_NIX_SHELL — an indicator that tells you whether the current environment was set up by nix-shell. it can have the values pure or impure.

📎 Appendix: OS-specific conventions

this info isn't Nix-specific at all, it's just referenced up above, so here's the cheat sheet 🍓

🐧 Unix: XDG Base Directories

The XDG Base Directory Specification defines standard locations for user-specific configuration, state, and cache files on Unix systems.

These are the environment variables it uses:

  • XDG_CONFIG_HOME (anchor #env-XDGCONFIGHOME) — default ~/.config
  • XDG_STATE_HOME (anchor #env-XDGSTATEHOME) — default ~/.local/state
  • XDG_CACHE_HOME (anchor #env-XDGCACHEHOME) — default ~/.cache
  • XDG_CONFIG_DIRS (anchor #env-XDGCONFIGDIRS) — default /etc/xdg. it's a colon-separated list of additional configuration base directories, searched after XDG_CONFIG_HOME.

🪟 Windows: Known Folders

On Windows, Known Folders provide standard locations for application data.

The relevant folders are:

  • %APPDATA% (anchor #env-APPDATA) — per-user roaming application data
  • %LOCALAPPDATA% (anchor #env-LOCALAPPDATA) — per-user local application data
  • %PROGRAMDATA% (anchor #env-PROGRAMDATA) — system-wide application data

✨ Examples ✨

look at her go:

$ nix-env --switch-profile ~/my-profile

and that's the whole page, bestie!! 🥳 this one was the nix-env --switch-profile(1) page straight out of the Nix manual, and the footer down there just reads nix-env --switch-profile(1) — so consider the source, version and date all signed off on. go switch a profile, you absolute icon 👑💖

📦 where this page comes from