nix-store.2

Manages files in the Nix store

TLDR

Collect garbage, such as removing unused paths

$ nix-store --gc

Hard-link identical files together to reduce space usage

$ nix-store --optimise

Delete a specific store path (must be unused)

$ nix-store --delete [/nix/store/...]

Show all dependencies of a store path (package), in a tree format

$ nix-store [[-q|--query]] --tree [/nix/store/...]

Calculate the total size of a certain store path with all the dependencies

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

Show all dependents of a particular store path

$ nix-store [[-q|--query]] --referrers [/nix/store/...]

--add path
    Add the file or directory path to the Nix store.

--add-fixed kind path
    Add the file or directory path to the Nix store with a content-addressed name of the specified kind, e.g. sha256.

--verify
    Verify the integrity of the Nix store.

--gc
    Perform garbage collection to remove unused store paths.

--delete path
    Delete the store path.

--dump-db
    Dump the Nix store database.

--import path
    Import store paths from an export created by nix-store --export.

--export
    Export store paths so they can be imported to another nix store.

--repair-path path
    Attempt to repair missing files or directories.

--query-path-info path
    Query information about a store path.

--root path
    Register a path as a garbage collection root.

--log-path path
    Obtain the log path for a build.

DESCRIPTION

The nix-store command is a low-level tool for interacting with the Nix store. It is primarily used for managing store paths, such as adding files to the store, querying information about store paths, and performing garbage collection. While most users will interact with the Nix store through higher-level tools like nix build, nix-env, or nix copy, nix-store provides fine-grained control over the store's operations. Understanding nix-store can be helpful for debugging and advanced Nix usage. It allows manipulating derivations, realizing outputs, and generally introspecting the Nix store.

CAVEATS

Using nix-store directly requires a good understanding of the Nix store and its workings. Incorrect usage can lead to data loss or a corrupted store.

EXIT STATUS

nix-store returns 0 on success and a non-zero value on failure. Specific error codes may vary depending on the subcommand and the nature of the failure.

ENVIRONMENT VARIABLES

nix-store respects environment variables such as NIX_PATH (for finding Nix expressions), NIX_CONF_DIR (for locating the Nix configuration file), and http_proxy.

HISTORY

nix-store has been a core component of Nix since its inception. Its functionality has evolved over time to support new features and optimizations in the Nix store. The interface, although low-level, has remained relatively stable, reflecting the foundational role it plays within the Nix ecosystem.