NIX-ENV-LIST-GENERATIONS(1)

📦
version 2.35.3 · 10 versions
, in fedora 44

💖 NAME 💖

nix-env --list-generations — okay so this is the one that lists your profile generations, bestie, and yes it's exactly as iconic as it sounds 💅

✨ SYNOPSIS ✨

nix-env --list-generations

That's it. That's the whole thing. No arguments, no chaos, just vibes 🌸

🌈 DESCRIPTION 🌈

So basically? This operation prints out a list of every generation that currently exists for the active profile. Like, all of them. The whole timeline. Your profile's entire lore 🫶

And babes, these are the ones you can switch between using the --switch-generation operation — so this list is lowkey your menu of options, iykyk.

It also prints the creation date of each generation, and it flags which one is the current generation. So you always know exactly where you're standing. Main character energy tbh 👑

🎀 OPTIONS 🎀

Okay so heads up: these following options are allowed for all nix-env operations, but ngl they might not always have an effect. Situational. Depends on the operation. Just so you know 💜

  • --file, -f _path_ — this one specifies the Nix expression (we're calling it the active Nix expression down below, keep up bestie) that gets used by the --install, --upgrade, and --query --available operations to obtain derivations. The default? ~/.nix-defexpr. That's the one it reaches for if you don't say anything 🌸

And here's the fun part: 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. So remote. Very digital. But listen — that tarball must include a single top-level directory containing at least a file named default.nix. No default.nix? No dice, bestie 💀

  • --profile, -p _path_ — this specifies the profile to be used by those operations that operate on a profile (aka the active profile, yes we're doing the naming thing again). A profile is a sequence of user environments called generations, and one of them is the current generation. So it's giving... a stack of eras. A timeline. Very reputation-coded 🦋
  • --dry-run — for the --install, --upgrade, --uninstall, --switch-generation, --delete-generations and --rollback operations, this flag makes nix-env print out what it would do if this flag hadn't been specified — without actually doing it. A little preview. A trailer. No consequences, just information 🎀

And that's not all — --dry-run also prints out which paths will be substituted (i.e., downloaded) and which paths will be built from source (because there's no substitute available). So you know exactly what's coming 🔥

  • --system-filter _system_ — by default, operations like --query --available show derivations matching any platform. This option lets you narrow it down and use derivations for the specified platform system instead. Filtering. Curating. We love a narrowed vibe check ✨
fr fr, that's a lot of options for a page about listing generations — but the rules say every one of them shows up, so here we are 💖

🎀 Common Options 🎀

Most Nix commands take these bad boys, so bestie, you're gonna see them literally everywhere. Learn them once, slay forever. 💅

  • --help — prints a lil' summary of the command syntax and then dips. So useful, so iconic.
  • --version — prints the Nix version number on standard output and exits. That's it, that's the whole job. ✨
  • --verbose, -v — turns the dial UP on diagnostic messages printed to standard error. Here's the tea: for every Nix operation, what lands on standard output is well-defined, but any diagnostic info goes to standard error, never to standard output. Periodt.

You can stack this option over and over. Right now these are the verbosity levels that exist:

  • 0 "Errors only" — only prints messages telling you why the Nix invocation flopped. 💀
  • 1 "Informational" — prints helpful messages about what Nix is doing. This is the default, bestie.
  • 2 "Talkative" — more informational messages.
  • 3 "Chatty" — even more informational messages.
  • 4 "Debug" — prints debug info.
  • 5 "Vomit" — prints vast amounts of debug info. It's giving chaos, but in a productive way. 🤢✨
  • --quiet — turns the dial DOWN on diagnostic messages printed to standard error. It's the inverse option to -v / --verbose. You can stack this one too — check the verbosity levels list above. 🫶
  • --log-format format — changing 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. Do not be caught off guard, beloved.
  • bar — only displays a progress bar during the builds.
  • bar-with-logs — displays the raw logs, with the progress bar at the bottom.
  • --no-build-output, -Q — by default, output that builders write to standard output and standard error gets echoed to the Nix command's standard error. This option suppresses that behaviour. Important though: the builder's standard output and error are always written to a log file in prefix/nix/var/log/nix. No cap. 🌸
  • --max-jobs, -j number — sets the maximum number of build jobs Nix will run in parallel to that number. Say auto and it'll use however many CPUs the system has. The default comes from the max-jobs configuration setting, which itself defaults to 1. A bigger value hits different on SMP systems, or when you wanna exploit I/O latency. 🏃♀️💨

Set it to 0 and building on the local machine is disallowed — which is exactly what you want when builds should only happen on remote builders.

  • --cores — sets the value of the NIX_BUILD_CORES environment variable in the invocation of builders. Builders can use that variable however they like 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 that's set, or 1 otherwise. The value 0 means the builder should use all available CPU cores in the system. Go off, honestly. 🔥
  • --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 specified by the max-silent-time configuration setting. 0 means no time-out.
  • --timeout — sets the max number of seconds a builder can run. The default is specified by the timeout configuration setting. 0 means no timeout.
  • --keep-going, -k — keeps going when builds fail, to the greatest extent possible. Meaning: if building an input of some derivation fails, Nix will still build the other inputs — just not the derivation itself. Without this option, Nix stops as soon as any build fails (except builds of substitutes), and may even kill builds that are in progress, in case of parallel or distributed builds. Dramatic much? 😭
  • --keep-failed, -K — says that if a build fails, the temporary directory the build happens in (usually in /tmp) should not be deleted. The path of that build directory gets printed as an informational message, so you can go investigate. 🔍
  • --fallback — whenever Nix tries to build a derivation whose output paths all have known substitutes, but realising those output paths through the substitutes fails, it falls back on building the derivation instead.

The most common scenario where this saves you: you've registered substitutes to do binary distribution from, like, a network repository. If that repo is down, realising the derivation just fails. With this option, Nix builds the derivation instead — so installing from binaries falls back on installing from source. It's not the default because it's generally not desirable for a transient failure in getting substitutes to lead to a full build from source, with all the resource consumption that comes with it. Highkey expensive. 💸

  • --readonly-mode — with this option, no attempt is made to open the Nix database. Most Nix operations genuinely need database access, so those operations will just fail. Sorry bestie.
  • --arg name value — this option is accepted by nix-env, nix-instantiate, nix-shell and nix-build. When evaluating Nix expressions, the expression evaluator automatically tries to call functions it encounters. It can automatically call functions where 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 calls it with 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 gets called automatically using the value builtins.currentSystem for the system argument. You can override that with --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. Don't ask, just do it. 🙈)

  • --arg-from-file name path — passes the contents of file path as the argument name to Nix functions.
  • --arg-from-stdin name — passes the contents of stdin as the argument name to Nix functions.
  • --argstr name value — like --arg, except the value is not a Nix expression but a string. So instead of --arg system "i686-linux" (those outer quotes are there to keep the shell happy), you can just say --argstr system i686-linux. So much cleaner, honestly. ✨
  • --attr, -A attrPath — selects 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. Check nix-env --install for some concrete examples. 👑

Besides 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, it's zero-indexed. Yes, that's the vibe.

  • --eval-store store-url — the URL of the Nix store to use for evaluation, i.e. where to store derivations (.drv files) and the 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 a shell that already contains the built packages, ready to use, hand your expression to the nix-shell --packages convenience flag instead. 🐚

  • -I, --include path — adds an entry to the list of search paths used to resolve lookup paths. You can give this option multiple times.

Paths added through -I take precedence over the nix-path configuration setting and the NIX_PATH environment variable. Precedence, bestie. 🌈

  • --impure — allows access to mutable paths and repositories. Live a little. 🦋
  • --option name value — sets the Nix configuration option name to value. This overrides settings in the Nix configuration file (see nix.conf(5)).
  • --repair — fixes corrupted or missing store paths by redownloading or rebuilding them. Heads up: 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 — the location of the Nix profile. It defaults to the target of the symlink ~/.nix-profile if that symlink exists, or /nix/var/nix/profiles/default otherwise. Easy peasy. 💖

🫶 Common Environment Variables 🫶

ok so most Nix commands are out here reading the same little stack of environment variables like it's a group chat they're all in. here's the whole roster 💖

✨ Configuration environment variables ✨

these ones control how Nix loads its config. full deets live in the configuration file documentation, but here's the vibe:

  • NIX_CONF_DIR — overrides the system configuration directory, bestie. yes, the system one.
  • NIX_USER_CONF_FILES — overrides where your user configuration files live.
  • NIX_CONFIG — lets you drop configuration settings inline, no file required, we love convenience.

🛒 Store setting environment variables 🛒

  • NIX_IGNORE_SYMLINK_STORE — so normally the Nix store directory (typically /nix/store) is not allowed to contain any symlink components, periodt. why? to prevent "impure" builds, because builders sometimes "canonicalise" paths by resolving all symlink components. which means builds on different machines — where /nix/store resolves to different locations — could yield different results. generally not a problem, EXCEPT when builds get deployed to machines where /nix/store resolves differently. so if you're 100% sure you're not gonna do that, you can set NIX_IGNORE_SYMLINK_STORE to 1. slay, but carefully.

also ngl, if you're symlinking the store just to put it on another file system than the root file system, on Linux you're better off using bind mount points, like:

$ mkdir /nix
$ mount -o bind /mnt/otherdisk/nix /nix
consult the mount 8 manual page for the details, iykyk 🧚
  • NIX_STORE_DIR — overrides the location of the Nix store. 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; the default is %PROGRAMDATA%\nix\store, determined at runtime using the %PROGRAMDATA% Known Folder.

see the Store Types chapter — each store has a store setting linking back to this as its default 🔥

  • NIX_LOG_DIR — overrides the location of the Nix log directory. on Unix the default is /nix/var/log/nix, set at compile time by the log-dir build option. on Windows again, 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 the location of the Nix state directory. on Unix the default is ${localstatedir}/nix, where localstatedir is a compile-time build option defaulting to /nix/var. on Windows, no compile-time setting; the default is %PROGRAMDATA%\nix\state, determined at runtime using the %PROGRAMDATA% Known Folder.

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

  • NIX_DAEMON_SOCKET_PATH — overrides the path to the Unix domain socket used to talk to the Nix daemon. defaults to daemon-socket/socket within the state directory (see NIX_STATE_DIR).

see the Local Daemon Store documentation for the details on how the socket path gets resolved 💅

  • TMPDIR — use the specified directory to store temporary files. this includes temporary build directories in particular, and bestie those can take up substantial amounts of disk space. default is /tmp.
  • NIX_REMOTE — overrides the store setting.

🧠 Nix language evaluator settings 🧠

  • NIX_SHOW_STATS — if set to 1, Nix prints some evaluation statistics, like the number of values allocated. numbers go brrr.
  • NIX_COUNT_CALLS — if set to 1, Nix prints how often functions were called during Nix expression evaluation. super useful for profiling your Nix expressions ✨
  • GC_INITIAL_HEAP_SIZE — if Nix has been configured to use the Boehm garbage collector, this variable sets the initial size of the heap in bytes. defaults to 384 MiB. setting it low reduces memory consumption, but it'll increase runtime because of the overhead of garbage collection. trade-offs, we hate to see it 😭
  • 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.

it can be extended using 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. not a vibe.

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. these environment variables override where those live:

  • user configuration directory: NIX_CONFIG_HOME
  • user state directory: NIX_STATE_HOME
  • user cache directory: NIX_CACHE_HOME

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 (e.g. nix-env, nix-channel) use dotfiles in $HOME instead of these directories unless use-xdg-base-directories is enabled. new Nix commands (experimental) use the proper directories by default. glow up ✨

when use-xdg-base-directories is enabled, the configuration directory is resolved as:

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

likewise for the state and cache directories 💜

🌈 Miscellaneous environment variables 🌈

  • IN_NIX_SHELL — an indicator that tells you if 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, but it's referenced up above, so here it is anyway 🎀

🐧 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 involved:

  • XDG_CONFIG_HOME (default ~/.config)
  • XDG_STATE_HOME (default ~/.local/state)
  • XDG_CACHE_HOME (default ~/.cache)
  • XDG_CONFIG_DIRS (default /etc/xdg) — 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% — per-user roaming application data
  • %LOCALAPPDATA% — per-user local application data
  • %PROGRAMDATA% — system-wide application data

🌸 Examples 🌸

look at her go:

$ nix-env --list-generations
  95   2004-02-06 11:48:24
  96   2004-02-06 11:49:01
  97   2004-02-06 16:22:45
  98   2004-02-06 16:24:33   (current)

the (current) on generation <cyan>98</cyan>?? that's the main character right there 👑💅

aaand that's a wrap bestie 🫶 this whole thing came straight out of the nix-env --list-generations(1) page in the General Commands Manual — like, the Nix manual's general commands section, the nix-env --...enerations(1) one. you've officially read the whole thing, no cap. go touch some generations. 💖✨

📦 where this page comes from