nix-store.3

Collect garbage, i.e. remove unused paths to reduce space usage

$ nix store gc

$ nix store optimise

$ nix store delete /nix/store/[checksum-package-version.ext]

$ nix store --store [https://cache.nixos.org] ls /nix/store/[checksum-package-version.ext]

$ nix store diff-closures /nix/store/[checksum-package-version.ext] /nix/store/[checksum-package-version.ext]

nix-store [options] <command> [arguments...]

Common commands include:
nix-store --add <path>
nix-store --query {--hash | --references | ...} <store-path>
nix-store --gc
nix-store --verify

--add
    Adds a local file or directory to the Nix store, computing its hash and registering it. Useful for adding non-Nix paths.

--add-fixed
    Adds a fixed-output derivation path to the store, verifying its hash against the expected one (e.g., for source tarballs).

--export
    Exports specified store paths and their dependencies into a 'nar' (Nix Archive) format, typically sent to standard output.

--import
    Imports store paths from a 'nar' archive read from standard input into the Nix store.

--delete
    Deletes specified store paths from the database and disk. Use with extreme caution as it can break system integrity.

--query
    Queries various information about a store path. Sub-commands include --hash, --references (what it depends on), --referrers (what depends on it), --valid, etc.

--gc
    Performs garbage collection, removing store paths that are not referenced by any garbage collector roots (e.g., active user environments or profiles).

--verify {--all | --check-contents | ...}
    Verifies the integrity of store paths, checking their hashes and cryptographic signatures. Can also repair the store if issues are found.

--read-log
    Reads and prints the build log associated with a given store path, if available.

--print-roots
    Prints all currently registered garbage collector roots, which prevent specific store paths from being garbage collected.

-v, --verbose
    Increases the verbosity of output messages, providing more detailed information during operations.

--json
    Outputs results in JSON format where applicable, facilitating machine parsing.

The nix-store command is a fundamental, low-level utility within the Nix package manager. It directly interacts with the Nix store, which is the heart of Nix's reproducibility and atomic upgrades. The store, typically located at /nix/store, contains all installed packages, derivations, and their dependencies, identified by unique cryptographic hashes.

This command allows advanced users and Nix's internal machinery to perform critical operations such as adding new build outputs to the store, querying information about existing store paths (like their cryptographic hash, references, or referrers), and managing garbage collection to remove unreferenced data. While higher-level Nix commands like nix-build, nix-shell, and nix-env abstract away most of its direct usage, nix-store remains indispensable for inspecting the store's state, performing manual cleanups, or diagnosing issues. It enforces the immutability and integrity of all store paths, ensuring that package builds are consistent and verifiable.

This analysis is based on the standard nix-store(1) man page, which describes the user-facing command. The request specifically mentioned nix-store.3. As a common convention, .3 man pages refer to C library functions, which nix-store is not. There is no widely published nix-store.3 man page for the utility itself. It's possible the reference was to a specific, internal, or non-standard documentation section.

Direct use of nix-store is generally for advanced users or debugging. Misuse, especially with commands like --delete, can lead to a corrupted or non-functional Nix store. Many operations require root privileges or the nix-daemon to be running with appropriate permissions.

All build outputs and dependencies in Nix are stored in a unique, immutable location within the Nix store (e.g., /nix/store/<hash>-<name>). The <hash> component is a cryptographic hash of the input derivation, ensuring reproducibility and content-addressability. This structure is fundamental to Nix's ability to provide atomic upgrades, rollbacks, and side-by-side installations of different versions of the same software.

The nix-store --gc command is used to reclaim disk space by removing 'unreachable' store paths. A path is unreachable if it is not referenced by any 'garbage collector root' (e.g., active user environments, profiles, or explicitly registered roots). This process helps maintain a clean and efficient Nix store, crucial for systems with many builds or frequent updates.

The Nix Archive (NAR) is a simple, self-describing, and canonical serialization format used by Nix for packaging and exchanging store paths. Commands like nix-store --export and nix-store --import leverage this format to facilitate copying store paths between different Nix installations or for backup purposes, ensuring integrity and completeness.

The nix-store utility is an integral and foundational component of the Nix package manager, which was originally conceived and developed by Eelco Dolstra starting around 2003. Its design principles, such as content-addressable storage and immutable build outputs, were central to Nix's vision from its inception. The existence of a dedicated, low-level store manipulation tool reflects Nix's commitment to a purely functional build model. While the Nix ecosystem has grown significantly, introducing higher-level commands and concepts, the core functionality and role of nix-store have remained consistent, serving as the bedrock for all Nix operations.

nix(1), nix-build(1), nix-shell(1), nix-collect-garbage(1), nix-daemon(8)