nix-store.2

Collect garbage, such as removing unused paths

$ nix-store --gc

$ nix-store --optimise

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

$ nix-store [[-q|--query]] --tree /nix/store/[checksum-package-version.ext]

$ du [[-cLsh|--total --dereference --summarize --human-readable]] $(nix-store [[-q|--query]] --references /nix/store/[checksum-package-version.ext])

$ nix-store [[-q|--query]] --referrers /nix/store/[checksum-package-version.ext]

nix-store { --query | --add | --delete | --verify-paths | --repair | --read-log | --export | --import | --realise | --optimise-store | --gc } [options...] [paths...]

--add paths
    Adds the specified paths to the Nix store. Generally discouraged for direct use; higher-level tools are preferred.

--query [sub-options] paths
    Queries various information about specified store paths, e.g., roots, references, referrers, build logs, etc.

--realise derivations
    Builds (realises) the specified derivations. This process fetches or builds all necessary dependencies.

--optimise-store
    Finds identical files or subtrees in the Nix store and hard-links them to save disk space.

--gc [options]
    Performs garbage collection on the store, deleting unreachable store paths that are no longer referenced by roots.

--verify-paths [--check-contents] paths
    Verifies the integrity of specified store paths, optionally checking file contents against their cryptographic hashes.

--repair paths
    Attempts to repair damaged store paths by re-downloading or rebuilding them.

--read-log paths
    Displays the build log for specified store paths, useful for debugging build failures.

--export paths
    Exports specified store paths and their dependencies into a Nix Archive (NAR) file, typically streamed to standard output.

--import
    Imports store paths from a Nix Archive (NAR) file, typically read from standard input, adding them to the store.

--delete paths
    Deletes specified store paths. Use with extreme caution as it bypasses dependency checks; --gc is safer.

-d, --debug
    Enables debugging output, providing more detailed information about operations.

--store uri
    Specifies the Nix store to use, overriding the default /nix/store or NIX_STORE_DIR environment variable.

--option name value
    Sets a Nix configuration option for the duration of this command invocation.

The nix-store command is the low-level interface to the Nix store, the central component of the Nix package manager. It allows users and Nix itself to add, query, verify, and manipulate paths within the /nix/store directory. All build outputs and dependencies are stored here under cryptographic hashes, ensuring immutability and reproducibility. This command is primarily used by higher-level Nix tools like nix-build, nix-instantiate, and nix-shell, but can also be invoked directly for specific store management tasks such as garbage collection, repairing damaged paths, or inspecting store contents. It is fundamental to Nix's content-addressable design and ensures software integrity and reliable deployments.

Direct manipulation of the Nix store using nix-store with flags like --add or --delete is generally not recommended for everyday use, as it can inadvertently break dependencies or corrupt the store state. Higher-level tools like nix-build, nix-shell, and nix-gc provide safer and more robust ways to interact with the store. Operations that modify the store often require root privileges.

The Nix store is typically located at /nix/store. All software packages, dependencies, and build outputs are stored as immutable, content-addressed paths within this directory. Each path's name is prefixed with a cryptographic hash (e.g., /nix/store/<hash>-<name>), ensuring that changes to contents result in a new path and preventing conflicts.

The behavior of nix-store can be influenced by several environment variables, including:

NIX_STORE_DIR: Overrides the default location of the Nix store (e.g., /usr/local/nix/store).
NIX_REMOTE: Specifies a remote Nix store to connect to.
NIX_CONFIG: Provides additional Nix configuration options.

The nix-store command typically exits with a status of 0 upon successful execution. A non-zero exit status indicates an error or failure during the operation.

nix-store is one of the oldest and most fundamental components of the Nix ecosystem, originating from the early days of the Nix package manager's development (around 2003). It embodies the core principles of content-addressable storage and atomic upgrades that define Nix. While newer, higher-level commands like the unified nix CLI now abstract many of its functions, nix-store remains the direct interface for low-level interactions with the /nix/store. Its robust design has been central to Nix's success in achieving reproducible and reliable software deployments.

nix(1), nix-build(1), nix-env(1), nix-gc(1), nix-shell(1), nix-instantiate(1)