NIX-ENV-DELETE-GENERATIONS(1)

📦
version 2.35.3 · 11 versions
, in fedora 44

nix-env --delete-generations 💅

okay bestie, you found the nix-env --delete-generations page in the General Commands Manual and honestly? it's giving "profile glow-up". this is the one that deletes profile generations. no cap. let's get into it ✨

✨ NAME ✨

nix-env --delete-generations — delete profile generations 🗑️💖

✨ SYNOPSIS ✨

nix-env --delete-generations generations

✨ DESCRIPTION ✨

so basically this operation deletes the specified generations of the current profile. that's the whole vibe. periodt.

and generations can be one of the following cuties:

  • <number>... — a list of generation numbers, each one a separate command-line argument. this deletes exactly the profile generations you name by their generation number. but heads up: deleting the current generation is not allowed. absolutely not. the current one is the main character and stays. 🙅‍♀️
  • the special value old — deletes all generations except the current one. all of them. yes.
⚠️ WARNING ⚠️ older and newer generations will be deleted by this operation. not just the older ones. bestie, read this part twice. one might expect this to just delete older generations than the current one, but that is only true if the current generation is also the latest. because you can roll back to a previous generation, it is possible to have generations newer than the current one. and those will also be deleted. 💀 so like. vibe check before you run this.
  • <number>d — the last number days. example: 30d. deletes all generations created more than number days ago, except the most recent one of them. this is the cute one because it lets you roll back to generations that were available within the specified period. 🦋
  • +<number> — the last number generations up to the present. example: +5. keeps the last number generations, along with any newer than current. 🎀

lowkey important: periodically deleting old generations is important to make garbage collection effective. why? because profiles are also garbage collection roots — any store object reachable from a profile is "alive" and ineligible for deletion. so like, if you never clean up, your store just keeps growing forever and the garbage collector literally cannot touch it. the way that a profile keeps everything alive... it's giving hoarder energy. 😭 clean up your generations and the GC can actually do its job. iykyk.

✨ OPTIONS ✨

these following options are allowed for all nix-env operations, but ngl they may not always have an effect. depends on the operation bestie. 💅

  • --file, -f path — specifies the Nix expression (designated below as the active Nix expression) used by the --install, --upgrade, and --query --available operations to obtain derivations. the default is ~/.nix-defexpr. 🗂️

and here's the fun part: if the argument starts with http:// or https://, it is interpreted as the URL of a tarball that will be downloaded and unpacked to a temporary location. the tarball must include a single top-level directory containing at least a file named default.nix. one directory, got it? not zero, not five. ✨

  • --profile, -p path — specifies the profile to be used by those operations that operate on a profile (designated below as the active profile). and what even is a profile? a profile is a sequence of user environments called generations, one of which is the current generation. so yes, that's the thing we've been deleting bits of this whole time. we're so back. 👑
  • --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. the responsible queen behavior. 🫶

--dry-run also 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 tea before committing. 🙈

  • --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. so you can be picky. as you should be. 💅

🌸 part 1 done, and there's more coming bestie — don't go anywhere 🌸

🦋 Common Options 🦋

okay bestie, here's the tea 💅 most Nix commands accept the same little squad of command-line options, so learn these once and you've basically unlocked the whole family. no cap.

  • --help — prints out a summary of the command syntax and then dips out immediately. exits right after.
  • --version — prints out the Nix version number on standard output and exits. that's it, that's the whole vibe.
  • --verbose / -v — cranks up the level of verbosity for the diagnostic messages printed on standard error. here's the important bit: for each Nix operation, the info printed on standard output is well-defined, and any diagnostic info goes to standard error, never to standard output. ✨

This option may be specified repeatedly. Currently, the following verbosity levels exist:

  • 0 "Errors only" — only prints messages explaining why the Nix invocation failed. it's giving silent treatment.
  • 1 "Informational" — prints useful messages about what Nix is doing. this is the default, bestie 🎀
  • 2 "Talkative" — prints more informational messages.
  • 3 "Chatty" — prints even more informational messages.
  • 4 "Debug" — prints debug information.
  • 5 "Vomit" — prints vast amounts of debug information. literally a firehose 😭
  • --quiet — turns the verbosity of diagnostic messages printed on standard error down. it's the inverse option to -v / --verbose.

This option may be specified repeatedly. See the verbosity levels list above. 👆

  • --log-format format — use this to change the output of the log format. format is one of:
    • raw — this is 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 hardcode-parsing it and then act surprised, iykyk.
  • bar — only display a progress bar during the builds.
  • bar-with-logs — display the raw logs, with the progress bar at the bottom.
  • --no-build-output / -Q — by default, the output written by builders to standard output and standard error is echoed to the Nix command's standard error. this option suppresses that behaviour. note that the builder's standard output and error are always written to a log file in prefix/nix/var/log/nix, so nothing's actually lost, we're just being quiet about it 🤫
  • --max-jobs / -j number — sets the maximum number of build jobs that Nix will perform in parallel to the specified number. specify auto to use the number of CPUs in the system. the default is specified 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. multitasking icon behaviour 👑

Setting it to 0 disallows building on the local machine, which is useful when you want builds to happen only on remote builders.

  • --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 that the builder should use all available CPU cores in the system. go girl give us everything 🔥
  • --max-silent-time — sets the maximum number of seconds that 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 maximum number of seconds that a builder can run. the default is specified 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 is, 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 — specifies that in case of a build failure, the temporary directory (usually in /tmp) in which the build takes place should not be deleted. the path of the build directory is printed as an informational message. perfect for when you wanna snoop on the aftermath 🔍
  • --fallback — whenever Nix attempts 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 in which this is useful is when we have registered substitutes in order to perform binary distribution from, say, a network repository. if the repository is down, the realisation of the derivation will fail. when this option is specified, Nix will build the derivation instead. thus, installation from binaries falls back on installation from source. 🌈

this option is not the default since it is generally not desirable for a transient failure in obtaining the substitutes to lead to a full build from source (with the related consumption of resources). like, imagine rebuilding the whole world because wifi blinked. no thank you 💀

  • --readonly-mode — when this option is used, no attempt is made to open the Nix database. most Nix operations do need database access, so those operations will fail. it's giving look-don't-touch.
  • --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. shell girlies know 😌)

  • --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 option 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 say --argstr system i686-linux. way less escaping drama, obsessed 💖
  • --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 bestie, counting starts at zero, it's giving programmer brain 🧠)

  • --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. ✨

  • -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. main character privilege, honestly 👑

  • --impure — allow access to mutable paths and repositories.
  • --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. 😭 it's giving "worth it but bring snacks".
Note 📝 see man nix.conf for overriding configuration settings with command line flags.

🦋 Environment variables 🦋

  • NIX_PROFILE — the location of the Nix profile. defaults to the target of the symlink ~/.nix-profile, if it exists, or /nix/var/nix/profiles/default otherwise.

✨ Common Environment Variables ✨

Okay bestie, so like most Nix commands out here read these environment variables 👀 — they're the shared vocabulary, the group chat everyone's in.

🎀 Configuration environment variables 🎀

These ones decide how Nix loads its config. The configuration file docs have the full tea, but here's the short version:

  • 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 hand Nix configuration settings inline. no file, just vibes ✨

🛒 Store setting environment variables 🛒

  • NIX_IGNORE_SYMLINK_STORE — ngL, normally the Nix store directory (usually /nix/store) is not allowed to contain any symlink components, because that would let "impure" builds sneak in 💀. Here's the why: builders sometimes "canonicalise" paths by resolving every symlink component. So builds on different machines (where /nix/store resolves to different places) could hand you different results. Usually that's not a problem — except when builds get deployed to machines where /nix/store resolves differently. If you're sure that's not your situation, set NIX_IGNORE_SYMLINK_STORE to 1.
🫶 little tip from the original: if you're symlinking the Nix store just to put it on a different 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

And go read the mount 8 manual page for the details, periodt.

  • 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 at all; the default is %PROGRAMDATA%\nix\store, determined at runtime using the %PROGRAMDATA% Known Folder.

See the Store Types chapter — every store has a store setting that links back to this one 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, the Local Daemon Store, and the Experimental SSH Store with filesystem mounted each have per-store settings that override this one 🌈

  • 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.

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

  • 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 (see NIX_STATE_DIR). Check the Local Daemon Store docs for the full story on how the socket path gets resolved 🔌
  • TMPDIR — use this directory to store temporary files. Specifically, that includes temporary build directories, which can eat up a substantial amount of disk space — be so fr about your disk, bestie 😭. Default is /tmp.
  • NIX_REMOTE — overrides the store setting.

🧠 Nix language evaluator settings 🧠

  • NIX_SHOW_STATS — if you set it to 1, Nix prints some evaluation statistics, like how many values got allocated. numbers go brrr 📊
  • NIX_COUNT_CALLS — if you set it to 1, Nix prints how often functions were called while evaluating Nix expressions. perfect for profiling your Nix expressions, iykyk.
  • 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 means less memory consumption but a longer runtime, thanks to garbage collection overhead. trade-offs, the way that life works 💜
  • 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 — okay love this for us:

$ 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 does per-user configuration, state, and cache directories, because of course it does — main character energy ✨. These environment variables override where those directories live:

  • [user configuration directory]{#user-conf-dir}: [NIX_CONFIG_HOME]{#env-NIXCONFIGHOME}
  • user state directory: [NIX_STATE_HOME]{#env-NIXSTATEHOME}
  • user cache directory: [NIX_CACHE_HOME]{#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. New Nix commands (the experimental ones) 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)

And likewise for the state and cache directories. consistent queen 💅

🍓 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, but it got referenced up above, so here it is.

☀️ Unix: XDG Base Directories

The XDG Base Directory Specification defines standard locations for user-specific configuration, state, and cache files on Unix systems. The following environment variables are used:

  • [XDG_CONFIG_HOME]{#env-XDGCONFIGHOME} (default ~/.config)
  • [XDG_STATE_HOME]{#env-XDGSTATEHOME} (default ~/.local/state)
  • [XDG_CACHE_HOME]{#env-XDGCACHEHOME} (default ~/.cache)
  • [XDG_CONFIG_DIRS]{#env-XDGCONFIGDIRS} (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%]{#env-APPDATA} — per-user roaming application data
  • [%LOCALAPPDATA%]{#env-LOCALAPPDATA} — per-user local application data
  • [%PROGRAMDATA%]{#env-PROGRAMDATA} — system-wide application data

🔥 Examples 🔥

Time for the actual receipts, bestie. these are the moments.

✂️ Delete explicit generation numbers

$ nix-env --delete-generations 3 4 8

Deletes the generations numbered 3, 4, and 8 — as long as the currently active generation isn't one of them. (don't delete the one you're standing on, babe 🙈)

➕ Keep most-recent by count (number of generations)

$ nix-env --delete-generations +5

Say 30 is the current generation, and you've currently got generations numbered 20 through 32.

Then this command deletes generations 20 through 25 (<= 30 - 5), and keeps generations 26 through 31 (> 30 - 5). math ate, honestly 👑

⏳ Keep most-recent by time (number of days)

$ nix-env --delete-generations 30d

This one deletes all generations older than 30 days — except for the generation that was active 30 days ago, if it still exists. sentimental exception ✨

🧹 Delete all older

$ nix-env --profile other_profile --delete-generations old
and that's the whole page! 💖 if you made it here you're literally a Nix scholar now, no cap.

okay so that was nix-env --delete-generations(1) — Nix 2.34.7, dated 2026-02-06 🎀 slay, go delete some generations responsibly, bestie 💅🦋

📦 where this page comes from