nix-store

View documentation for the traditional store

$ tldr nix-store.2

$ tldr nix store.3

nix-store [options] [arguments]
nix-store --add path
nix-store --realise paths...
nix-store --query {--roots | --referrers | --references | --requisites | --outputs | --deriver | --hash | --name} path
nix-store --gc [--print-roots]
nix-store --delete paths...
nix-store --verify [--check-contents]

--add <path>
    Adds path to the Nix store, computing its hash and copying contents. Returns the new store path.

--realise <paths...>
    Builds (realises) the specified derivation outputs or store paths, making them available in the store.

--query <mode> <path>
    Queries information about path based on the specified mode (e.g., --roots, --referrers, --references, --requisites, --outputs, --deriver, --hash, --name).

--gc
    Performs garbage collection, identifying and removing unreferenced store paths to free up disk space.

--delete <paths...>
    Deletes specific store paths from the Nix store. This operation usually requires root privileges or Nix daemon interaction.

--verify
    Verifies the cryptographic integrity of store paths. Use --check-contents to verify the actual contents against their hashes.

--read-log <path>
    Reads and prints the build log for a given derivation output path.

--print-roots
    Used in conjunction with --gc to print the list of current garbage collection roots.

-I <path> or --include <path>
    Adds path to the Nix expression search path, used for resolving import expressions.

--max-jobs <N>
    Sets the maximum number of parallel build jobs that Nix can run.

--option <name> <value>
    Overrides a Nix configuration option for the duration of the command's execution.

--xml
    Produces XML output for query commands, which is useful for programmatic parsing.

nix-store is a fundamental, low-level command-line utility within the Nix package manager ecosystem. It provides direct interaction with the Nix store, typically located at /nix/store. This directory is the core of Nix's reproducibility and atomic upgrades, as it uniquely identifies and stores every component of a system – packages, derivations, and their dependencies – by cryptographic hash.

Unlike higher-level Nix commands like nix build or nix shell, nix-store operates on the raw store paths. It's primarily used by Nix itself to perform operations like building derivations (realising outputs), adding new paths to the store, querying relationships between store paths (e.g., dependencies or reverse dependencies), and performing garbage collection to remove unreferenced data. While not typically used by end-users for daily package management, understanding nix-store is crucial for advanced Nix development, debugging, and system administration, offering granular control over the immutable package store.

nix-store is a low-level command; improper use can lead to an inconsistent or corrupted Nix store.
Most write operations (e.g., adding, deleting, or realising paths) require root privileges or running through the Nix daemon.
Its functionality is progressively being integrated into the higher-level nix command (e.g., nix build, nix store gc), making nix-store less frequently used directly by end-users over time.

The /nix/store directory, managed by nix-store, is unique. Every path in it is identified by a cryptographic hash of its inputs, making it content-addressed and immutable. This ensures that a build result is always the same given the same inputs, crucial for reproducibility and atomic upgrades. Directly manipulating paths in /nix/store outside of nix-store or the Nix daemon is generally not recommended.

Nix's garbage collection, performed via nix-store --gc, only deletes paths that are not 'reachable' from designated garbage collection roots. These roots are typically system profiles, user environments, or explicitly registered paths that the user or system wants to keep. Understanding and managing roots is key to effective store cleanup.

nix-store has been a foundational component of the Nix package manager since its inception, embodying the core logic for managing the immutable content-addressed store. While its direct command-line use has gradually diminished for everyday tasks due to the introduction of the more user-friendly unified nix command (starting with Nix 2.0), nix-store remains the underlying engine for many higher-level Nix operations. Its design is central to Nix's principles of reproducible builds and atomic upgrades.

nix(1), nix-build(1), nix-instantiate(1), nix-shell(1), nix-daemon(8)