Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 36 ยท Dependencies and Repositories

Dependency Resolution and Version Conflicts in Gradle

Learn how Gradle resolves transitive dependencies, picks the highest version in a conflict, and how to read dependency trees, dependencyInsight and force or strict versions.

You declare a handful of direct dependencies, yet a real project's classpath may contain a hundred jars. The rest are transitive dependencies: the libraries your libraries need. When two of them ask for different versions of the same module, Gradle must choose one. Understanding how it chooses, and how to see and steer the decision, is the difference between "it works on my machine" and a build you can trust.

The Gradle commands are read-only. The stand-ins implement the conflict rule and a dependency tree printer in Java.

Transitive dependencies

Every published library carries metadata (a POM or Gradle module file) listing its own dependencies. Gradle downloads that metadata, follows the edges, and builds a dependency graph.

flowchart LR
  App["app"] --> A["lib-a 1.0"]
  App --> B["lib-b 2.0"]
  A --> J1["json 1.2"]
  B --> J2["json 1.5"]
  J2 --> U["util 3.0"]

app never mentions json, but both of its dependencies do, and with different versions.

Gradle resolves the graph once per configuration and ends with exactly one version of each module on the classpath.

The conflict rule: the highest version wins

When the same module appears with several versions in a graph, Gradle selects the highest one by default (unlike Maven, which prefers the nearest declaration). In the picture, json 1.5 wins over 1.2, and lib-a will run against a newer json than it asked for. That is usually fine thanks to semantic versioning, but not always.

Versions are compared part by part: 1.10 is higher than 1.9, and qualifiers such as -alpha, -rc1 sort below the release.

Looking at the graph

Terminal
./gradlew :app:dependencies --configuration runtimeClasspath
TEXT
runtimeClasspath - Runtime classpath of source set 'main'.
+--- com.example:lib-a:1.0
|    \--- com.example:json:1.2 -> 1.5
\--- com.example:lib-b:2.0
     \--- com.example:json:1.5
          \--- com.example:util:3.0

Reading it: 1.2 -> 1.5 means "requested 1.2 but resolved to 1.5". A (*) at the end of a line means this subtree is shown elsewhere. A (c) marks a constraint, and FAILED marks an unresolvable module.

To see why a module has a version, ask for an insight report:

Terminal
./gradlew :app:dependencyInsight --dependency json --configuration runtimeClasspath
TEXT
com.example:json:1.5
   Variant runtime:
      ...
   Selection reasons:
      - By conflict resolution : between versions 1.5 and 1.2

com.example:json:1.5
\--- com.example:lib-b:2.0
     \--- runtimeClasspath

com.example:json:1.2 -> 1.5
\--- com.example:lib-a:1.0
     \--- runtimeClasspath

The selection reason, "By conflict resolution", answers the usual question: who forced this version? You can also run ./gradlew buildEnvironment for build script dependencies.

Stand-in: the highest version wins

This Java program is not Gradle, but it implements the same rule: collect every requested version of each module while walking the graph, then choose the highest by comparing numeric parts.

Java Stand-in: conflict resolution by highest version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that 1.10 beats 1.2: versions are compared numerically per part, not as text. Sorting the strings alphabetically would pick the wrong one.

Taking control

Sometimes the default outcome is wrong: a newer version breaks something, or a security fix demands an upgrade. You have several tools.

1. Declare the version you want directly. A direct declaration of a higher version wins, because it joins the conflict as one more request:

Kotlin
dependencies {
    implementation("com.example:lib-a:1.0")
    implementation("com.example:json:1.5")     // lifts json for everyone
}

2. Make a version strict. A strict version fails the build if the graph needs anything different, instead of silently upgrading:

Kotlin
implementation("com.example:json") {
    version { strictly("[1.2, 1.6[") ; prefer("1.5") }
}

3. Force a version in the resolution strategy (a blunt instrument that overrides the graph):

Kotlin
configurations.all {
    resolutionStrategy {
        force("com.example:json:1.5")
        failOnVersionConflict()          // optional: make every conflict an error
    }
}

4. Use a constraint (preferred for "if you need this module at all, use at least this version"): see Constraints, Platforms and Exclusions.

Prefer constraints and strict ranges over force; they are visible in dependencyInsight and are honored by consumers of your library.

Stand-in: printing a tree with resolved versions

The last stand-in prints a tree in the same shape as ./gradlew dependencies, marking requests that were upgraded.

Java Stand-in: a dependency tree like Gradle's

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Common causes of conflicts, and what to do

  • Two libraries on different majors of the same framework (Jackson, Netty, Spring): align them with a platform or BOM.
  • A library bundling its own copy of another (a "shaded" jar) hides the conflict from Gradle; look for duplicate classes at run time (NoSuchMethodError, ClassNotFoundException).
  • Unwanted transitive dependency: exclude it, or declare it compileOnly.
  • A security fix in a transitive library: add a constraint with a minimum version.
  • Reproducibility: use dependency locking (dependencyLocking { lockAllConfigurations() } and ./gradlew dependencies --write-locks) to record exactly what resolved.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Two libraries request json 1.2 and json 1.5. With default settings, which version does Gradle use?

    Gradle's default conflict resolution selects the highest requested version.
  2. 2. What does the line json:1.2 -> 1.5 mean in a dependency tree?

    The arrow shows the requested version on the left and the selected version on the right.
  3. 3. Which command explains why a particular module has the version it has?

    dependencyInsight shows the selection reasons and the paths that requested each version.
  4. 4. How are the versions 1.10 and 1.9 compared?

    Versions are compared part by part as numbers, so 10 is greater than 9.

Summary

  • Gradle resolves a graph of transitive dependencies and ends with one version per module.
  • On conflict, the highest version wins (Maven uses the nearest).
  • Read the graph with dependencies and dependencyInsight; a -> b means upgraded.
  • Steer decisions with a direct declaration, strict versions, constraints, or force as a last resort.
  • Lock versions for reproducible builds, and align related libraries with a platform.

Next: Constraints, Platforms and Exclusions