nix3-store
Manage the Nix store
TLDR
Collect garbage, i.e. remove unused paths to reduce space usage
Hard-link identical files together to reduce space usage
Delete a specific store path (most be unused)
List a contents of the store path, on a remote store
Show the differences in versions between two store paths, with their respective dependencies
SYNOPSIS
nix store
PARAMETERS
add-root PATH
Adds PATH as a garbage collector root, preventing it from being collected. Useful for keeping specific derivations or generations alive.
cat STORE_PATH
Prints the contents of a file inside a STORE_PATH to standard output. Useful for quickly inspecting configuration or source files.
copy PATH...
Copies one or more PATHs from a local or remote Nix store to another. Essential for setting up binary caches or distributing built artifacts.
gc [options]
Runs the garbage collector to delete unreachable paths from the Nix store, reclaiming disk space. Options control behavior like deletion dry-runs or maximum space to free.
path-info STORE_PATH...
Shows detailed information about one or more STORE_PATHs, including their closure size, references, and whether they are valid.
prefetch-url URL [options]
Downloads a file from a specified URL and adds it to the Nix store. Useful for fetching external sources with integrity checks.
read-log STORE_PATH
Reads and prints the build log for a given STORE_PATH, which can help in debugging failed builds or understanding build processes.
DESCRIPTION
The nix3-store command (part of the modern nix store command within the unified Nix CLI) provides a crucial low-level interface for interacting directly with the Nix store.
The Nix store is the foundational component of the Nix package manager, acting as a global, content-addressable, and immutable filesystem location (typically /nix/store) where all software components, configurations, and build artifacts are stored. Each path in the store is uniquely identified by a cryptographic hash of its inputs and dependencies, ensuring reproducibility and preventing conflicts.
This command allows users and automated systems to perform various operations on store paths, such as querying their information, adding or deleting garbage collector roots, copying paths between stores, running the garbage collector to reclaim disk space, and inspecting build logs. It's often used by Nix internals or for advanced debugging and system management, providing granular control over the integrity and state of the installed software ecosystem.
CAVEATS
Direct manipulation of the Nix store using nix store subcommands should be done with caution, as improper usage can lead to an inconsistent store state or break dependencies. Specifically, manually removing paths without using nix store gc is highly discouraged. Paths in the Nix store are immutable; once created, they cannot be modified. All changes result in new store paths.
CONTENT-ADDRESSABLE STORAGE
A core concept behind the Nix store is content-addressable storage. This means that every path in the store is named by a cryptographic hash of its complete set of inputs (source code, build scripts, dependencies, etc.). This ensures that if two different build processes produce the exact same output, they will share the same store path, leading to efficient storage and guaranteeing bit-for-bit reproducibility.
GARBAGE COLLECTION ROOTS
To prevent essential software from being deleted by the garbage collector (GC), Nix uses GC roots. These are symlinks from well-known locations (like user profiles or system configurations) pointing into the Nix store. Any store path reachable from a GC root is considered 'live' and will not be collected. nix store add-root explicitly creates such roots, ensuring specific derivations persist.
HISTORY
The functionality of nix store was historically provided by a standalone executable named nix-store. With the introduction of the unified Nix command-line interface (CLI), many of the legacy Nix commands were integrated as subcommands under the main nix executable. Thus, nix3-store (or `nix3` implying the unified CLI) refers to the nix store subcommand, signifying a shift towards a more consistent and user-friendly command structure while retaining the powerful low-level store management capabilities.
