nix-collect-garbage

Delete all store paths unused by current generations of each profile

$ sudo nix-collect-garbage [[-d|--delete-old]]

$ sudo nix-collect-garbage [[-d|--delete-old]] --dry-run

$ sudo nix-collect-garbage --delete-older-than 30d

nix-collect-garbage [OPTION...]

-d, --delete-old
    Deletes old garbage collector roots, effectively allowing previous system generations or user profiles to be collected.

--dry-run
    Performs a simulated garbage collection without actually deleting any paths, showing what would be freed.

-F BYTES, --max-freed BYTES
    Stops collecting garbage once at least BYTES amount of space has been freed. BYTES can be followed by k, M, G, or T.

-t BYTES, --trim-min-freed BYTES
    Continues collecting garbage until at least BYTES amount of space has been freed. BYTES can be followed by k, M, G, or T.

-s PATH, --store PATH
    Specifies the Nix store path to perform garbage collection on (defaults to /nix/store).

--gc-roots DIR
    Specifies an additional directory to scan for garbage collector roots.

--verbose
    Displays more detailed information about the garbage collection process.

nix-collect-garbage is a crucial utility for managing disk space within the Nix package manager's store. The Nix store, typically located at /nix/store, contains all built software packages, libraries, and their dependencies, identified by unique cryptographic hashes. Due to Nix's immutable design, paths within the store are never modified or overwritten; new versions of software result in new paths.

Over time, this can lead to an accumulation of unused or "dead" paths that are no longer referenced by any active system profile, user environment, or derivation. This command identifies and deletes such unreferenced paths, effectively reclaiming disk space. It works by determining the "garbage collection roots" – paths that are explicitly marked as in-use (e.g., your active NixOS system generation, user profiles, or explicitly registered roots). Any store path not reachable from these roots is considered garbage and eligible for deletion. Regularly running nix-collect-garbage is essential for maintaining a lean and efficient Nix system.

nix-collect-garbage deletes only paths that are not referenced by any declared garbage collection root. If you manually keep symlinks to store paths or directly reference them from outside a Nix-managed environment without registering them as roots, those paths might be deleted even if you consider them "in use." Always ensure important paths are part of a Nix profile or explicitly added as roots.

Running this command as root or with appropriate permissions is usually required to modify the Nix store.

In Nix, a "garbage collection root" is any file system path that points into the Nix store and is recognized by the garbage collector as a reason to keep the referenced store path (and its closure of dependencies) alive. Common roots include user profiles (created by nix-env), NixOS system generations (/run/current-system), and channel update symlinks. Only store paths not reachable from any active root are considered "garbage" and are subject to deletion by nix-collect-garbage.

By default, nix-collect-garbage performs an active collection, deleting identified garbage. The --dry-run option allows for a passive collection, merely reporting what would be deleted without making any changes. This is useful for previewing the impact of a garbage collection run before committing to it.

nix-collect-garbage is one of the original and core utilities in the Nix ecosystem, providing the fundamental mechanism for managing disk space by removing unreferenced store paths. It has been a part of Nix since its early development. While still functional and widely used, its functionality has been increasingly integrated and often superseded by the nix store gc subcommand within the newer, unified nix command-line tool, which offers a more consistent user experience across various Nix operations.

nix-store(1), nix(1), nix-env(1), nixos-rebuild(1)