nix-why-depends

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

$ nix why-depends [/run/current-system] /nix/store/[checksum-package-version.ext]

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

nix why-depends [OPTIONS] FROM-PATH TO-PATH

FROM-PATH
    The absolute path in the Nix store from which to start tracing dependencies. This is the 'source' of the dependency chain.

TO-PATH
    The absolute path in the Nix store that is the desired 'target' of the dependency chain. The command will search for paths leading to this store path.

--json
    Output the dependency paths in a structured JSON format, suitable for programmatic parsing.

--help
    Display a help message with usage information for the command.

--version
    Show the version of the Nix command-line tool.

nix why-depends is a powerful Nix command-line utility used to determine the dependency path(s) from a specified source Nix store path to a specified target Nix store path.

In the Nix ecosystem, every package, library, or configuration is represented by a unique cryptographic hash and stored in the /nix/store. Understanding these dependencies is crucial for debugging why a particular library or package is included in a larger build, optimizing build times by identifying unnecessary dependencies, or simply comprehending the intricate dependency graph of your NixOS system or Nix-built applications.

This command is especially useful for developers and system administrators working with complex Nix derivations, offering insights into the exact chain of dependencies that leads from one component to another, thereby simplifying dependency analysis and problem resolution within the Nix store.

The command operates on paths already present in the Nix store. It might be computationally intensive for extremely large and complex dependency graphs. Ensure FROM-PATH and TO-PATH are valid Nix store paths (e.g., /nix/store/hash-name).

By default, nix why-depends outputs a human-readable list of paths, indicating one or more direct or indirect dependency chains. When --json is used, the output is a JSON array of arrays, where each inner array represents a distinct dependency path from FROM-PATH to TO-PATH.

nix why-depends is a relatively modern addition to the Nix command-line interface, introduced as part of the unified nix command (e.g., nix help as opposed to older separate commands like nix-store, nix-build, etc.). This consolidation began gaining traction around Nix 2.4. Its purpose was to provide a more intuitive and direct way to query dependency paths compared to manually traversing the store using lower-level tools like nix-store -q --referrers.

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