skip to content

When and how do you use `dependencyInsight`, and how does it differ from `dependencies`?

level: middleimportance: must knowfreq 68%

answer

  1. reverse/inverse view of one module
  2. --dependency (substring) + --configuration
  3. shows selected version + selection reason
  4. by conflict resolution / by constraint / forced
  5. diagnose version skew

basics

~20 s

dependencyInsight traces why one specific module is on the classpath and which version won. You run gradle dependencyInsight --dependency <name> --configuration <name>. dependencies shows the whole tree; dependencyInsight is a focused, reverse view of one dependency.

solid answer

~40 s

Where `dependencies` prints the entire graph top-down, `dependencyInsight` answers the targeted question "why is *this* module at *this* version?". You invoke it with `--dependency <substring-or-coordinate>` and (usually) `--configuration <name>`. It shows the **selected version**, the **selection reason** (conflict resolution, a constraint, a `force`, a platform/BOM, a rich version), and then the **inverse paths** — every requesting path that pulled the module in, bottom-up to the roots. This is the canonical tool for diagnosing version-skew: when something resolved to an unexpected version, `dependencyInsight` tells you exactly which dependency requested it and what rule selected it. Note that `--configuration` is effectively required in newer Gradle because a module can resolve differently per configuration; `--dependency` matching is by substring, so `guava` matches `com.google.guava:guava`.

code

bash · 7 lines
bash
# Why is guava at the version it is, on the runtime classpath?
gradle dependencyInsight --dependency guava --configuration runtimeClasspath

# Typical top of report:
# com.google.guava:guava:32.1.3-jre
#   Selection reasons:
#     - By conflict resolution: between versions 32.1.3-jre and 30.0-jre

go deeper

for a junior

Know it exists and that it answers 'why this dependency/version', with --dependency and --configuration.

for a middle

Read selection reasons (conflict/constraint/forced) and the requester paths to drive a fix.

for a senior

Use it to root-cause version skew across modules and choose between constraint, exclude, platform bump, or strict version.

for a principal

Establish it as the org's standard triage tool and shape dependency-management (platforms/constraints) so its reports are predictable.

## The question each tool answers - `dependencies` — *forward* view: "given the roots, what does the whole graph look like?" - `dependencyInsight` — *reverse* view: "given one module, why is it here and at this version?" ## Invocation ```bash gradle dependencyInsight \ --dependency guava \ --configuration runtimeClasspath ``` - `--dependency` accepts a **substring** of the module coordinate, so `guava` matches `com.google.guava:guava`. You can also pass a full `group:name`. - `--configuration` selects which configuration to analyze. Because resolution can differ per configuration, this is essentially mandatory in modern Gradle (Gradle will error asking for it if a default can't be inferred). ## What the report contains 1. **Selected coordinate and version** at the top. 2. **Selection reason(s)** — for example: - `by conflict resolution: between versions 30.0 and 32.1.3` (highest wins), - `by constraint` (a `dependencies { constraints { } }` or platform/BOM entry), - `forced` (a `force` in a resolution strategy), - rich-version reasons (`required`, `strictly`, `prefer`, `reject`). 3. **Requesting paths** — the inverse tree: each leaf is a *requester*, walking up to a root project/configuration. This shows *who* asked for the module. ## Worked use case You see `NoSuchMethodError` from an old `commons-lang3`. `dependencyInsight --dependency commons-lang3` reveals it was forced to an old version by a BOM, and lists the three libraries that requested it — so you know whether to bump the BOM, add a constraint, or exclude. ## Mental model `dependencies` is the map; `dependencyInsight` is the GPS route to one address. Reach for insight the moment you ask "why *this* version?" rather than "what's on the classpath?".

  • Why does Gradle often require `--configuration` for `dependencyInsight`?
    A module can be selected differently in different configurations (e.g. compile vs runtime, or with test-only constraints). Without a configuration there's no single graph to analyze, so Gradle asks you to pick one.
  • If the report says `by constraint`, what does that tell you and how might you change the outcome?
    The version was pinned by a dependency constraint or a platform/BOM rather than direct selection. To change it you edit/override that constraint, bump the platform, or add your own higher-priority constraint.
  • Does `--dependency` need the full group:name?
    No — it matches by substring, so `guava` is enough; pass the full coordinate only to disambiguate when several modules match.

dependencies is the full subway map; dependencyInsight is the turn-by-turn route to one station, telling you which lines feed it.

saying these in an interview costs you the question

  • Saying it shows the forward tree like `dependencies` — it's the inverse, requester-oriented view.
  • Omitting `--configuration` and being surprised by the prompt/error.
  • Confusing 'requested' and 'selected' versions when reading selection reasons.

context

resolving links…