nix3-why-depends

Show why the currently running NixOS system requires a certain store path

$ nix why-depends [/run/current-system] [/nix/store/...]

$ nix why-depends --derivation [nixpkgs#dependent] [nixpkgs#dependency]

nix why-depends [OPTIONS] PATH...

PATH...
    One or more Nix store paths (e.g., /nix/store/<hash>-pkg) for which to find reverse dependencies. This is the specific item whose usage you want to investigate.

--recursive
    Recursively show all paths depending on the specified PATH, not just direct dependencies. This provides a comprehensive view of the entire dependency chain.

--roots
    In addition to showing paths depending on PATH, also display the ultimate garbage collector roots (e.g., user profiles, explicitly registered GC roots) that depend on those intermediate paths. This is particularly useful for understanding why something is not being garbage collected.

--json
    Output results in JSON format, which is ideal for programmatic parsing and integration with scripts or other tools.

--store STORE_URL
    Specify a different Nix store to query instead of the default local store.

The nix why-depends command, part of the modern Nix 3.x command-line interface, is a powerful tool for analyzing the dependency graph within the Nix store. Given a specific Nix store path (e.g., a package or library), it traverses the dependency graph in reverse to identify which other Nix store paths directly or indirectly depend on the specified item. This functionality is crucial for understanding disk space usage, debugging build inputs, and identifying components that are preventing others from being garbage collected. It helps users trace the chain of dependencies from a root down to a specific dependent path, providing clarity on how various parts of the Nix system are interconnected.

For Nix stores with a very large number of paths or deeply nested dependency graphs, the nix why-depends command can take a significant amount of time to compute and display results. The output, especially when using the --recursive option without specific filtering, can be quite extensive. It only reports on paths that are currently present in the Nix store; paths that have already been garbage collected will not appear in the results.

nix why-depends is frequently used for:
Disk Space Management: Identifying which large packages or profiles are pulling in specific dependencies, helping to inform decisions about what can be safely removed or optimized.
Debugging Build Failures: Tracing back dependencies to understand why a particular component is being built or is failing.
Garbage Collection Analysis: Determining which active roots (e.g., your user profile, generations) are preventing a specific store path from being garbage collected, thereby freeing up disk space.

By default, the command displays a human-readable tree-like structure. Each line represents a path in the dependency chain, with indentation indicating the depth of dependency. The specified PATH will typically appear at the bottom of a chain, with its direct and indirect reverse dependencies listed above it.

The functionality provided by nix why-depends has been a fundamental part of the Nix ecosystem for understanding store dependencies for many years. Originally, this capability was often exposed through a separate executable, nix-why-depends. With the evolution to the unified nix command-line interface (commonly referred to as the 'new CLI' or part of Nix 2.0+ and 3.x series), its functionality was integrated as a subcommand, making it more accessible and consistent with other Nix operations. Its core purpose of reverse dependency analysis has remained unchanged throughout its development.

nix-store(1), nix-gc(1), nix-build(1), nix-path-info(1)