In some situations, you might want to be in total control of the dependency graph. In particular, you may want to make sure that:

  • the versions declared in a build script actually correspond to the ones being resolved

  • or make sure that dependency resolution is reproducible over time

Gradle provides ways to perform this by configuring the resolution strategy.

Failing on version conflict

There’s a version conflict whenever Gradle finds the same module in two different versions in a dependency graph. By default, Gradle performs optimistic upgrades, meaning that if version 1.1 and 1.3 are found in the graph, we resolve to the highest version, 1.3. However, it is easy to miss that some dependencies are upgraded because of a transitive dependency. In the example above, if 1.1 was a version used in your build script and 1.3 a version brought transitively, you could use 1.3 without actually noticing.

To make sure that you are aware of such upgrades, Gradle provides a mode that can be activated in the resolution strategy of a configuration. Imagine the following dependencies declaration:

Example 1. Direct dependency version not matching a transitive version
build.gradle.kts
dependencies {
    implementation("org.apache.commons:commons-lang3:3.0")
    // the following dependency brings lang3 3.8.1 transitively
    implementation("com.opencsv:opencsv:4.6")
}
build.gradle
dependencies {
    implementation 'org.apache.commons:commons-lang3:3.0'
    // the following dependency brings lang3 3.8.1 transitively
    implementation 'com.opencsv:opencsv:4.6'
}

Then by default Gradle would upgrade commons-lang3, but it is possible to fail the build:

Example 2. Fail on version conflict
build.gradle.kts
configurations.all {
    resolutionStrategy {
        failOnVersionConflict()
    }
}
build.gradle
configurations.all {
    resolutionStrategy {
        failOnVersionConflict()
    }
}

Making sure resolution is reproducible

There are cases where dependency resolution can be unstable over time. That is to say that if you build at date D, building at date D+x may give a different resolution result.

This is possible in the following cases:

  • dynamic dependency versions are used (version ranges, latest.release, 1.+, …​)

  • or changing versions are used (SNAPSHOTs, fixed version with changing contents, …​)

The recommended way to deal with dynamic versions is to use dependency locking. However, it is possible to prevent the use of dynamic versions altogether, which is an alternate strategy:

Example 3. Failing on dynamic versions
build.gradle.kts
configurations.all {
    resolutionStrategy {
        failOnDynamicVersions()
    }
}
build.gradle
configurations.all {
    resolutionStrategy {
        failOnDynamicVersions()
    }
}

Likewise, it’s possible to prevent the use of changing versions by activating this flag:

Example 4. Failing on changing versions
build.gradle.kts
configurations.all {
    resolutionStrategy {
        failOnChangingVersions()
    }
}
build.gradle
configurations.all {
    resolutionStrategy {
        failOnChangingVersions()
    }
}

It’s a good practice to fail on changing versions at release time.

Eventually, it’s possible to combine both failing on dynamic versions and changing versions using a single call:

Example 5. Failing on non-reproducible resolution
build.gradle.kts
configurations.all {
    resolutionStrategy {
        failOnNonReproducibleResolution()
    }
}
build.gradle
configurations.all {
    resolutionStrategy {
        failOnNonReproducibleResolution()
    }
}

Getting consistent dependency resolution results

Dependency resolution consistency is an incubating feature

It’s a common misconception that there’s a single dependency graph for an application. In fact Gradle will, during a build, resolve a number of distinct dependency graphs, even within a single project. For example, the graph of dependencies to use at compile time is different from the graph of dependencies to use at runtime. In general, the graph of dependencies at runtime is a superset of the compile dependencies (there are exceptions to the rule, for example in case some dependencies are repackaged within the runtime binary).

Gradle resolves those dependency graphs independently. This means, in the Java ecosystem for example, that the resolution of the "compile classpath" doesn’t influence the resolution of the "runtime classpath". Similarly, test dependencies could end up bumping the version of production dependencies, causing some surprising results when executing tests.

These surprising behaviors can be mitigated by enabling dependency resolution consistency.

Enabling project-local dependency resolution consistency

For example, imagine that your Java library depends on the following libraries:

Example 6. First-level dependencies
build.gradle.kts
dependencies {
    implementation("org.codehaus.groovy:groovy:3.0.1")
    runtimeOnly("io.vertx:vertx-lang-groovy:3.9.4")
}
build.gradle
dependencies {
    implementation 'org.codehaus.groovy:groovy:3.0.1'
    runtimeOnly 'io.vertx:vertx-lang-groovy:3.9.4'
}

Then resolving the compileClasspath configuration would resolve the groovy library to version 3.0.1 as expected. However, resolving the runtimeClasspath configuration would instead return groovy 3.0.2.

The reason for this is that a transitive dependency of vertx, which is a runtimeOnly dependency, brings a higher version of groovy. In general, this isn’t a problem, but it also means that the version of the Groovy library that you are going to use at runtime is going to be different from the one that you used for compilation.

In order to avoid this situation, Gradle offers an API to explain that configurations should be resolved consistently.

Declaring resolution consistency between configurations

In the example above, we can declare that we want, at runtime, the same versions of the common dependencies as compile time, by declaring that the "runtime classpath" should be consistent with the "compile classpath":

Example 7. Declaring consistency between configurations
build.gradle.kts
configurations {
    runtimeClasspath.get().shouldResolveConsistentlyWith(compileClasspath.get())
}
build.gradle
configurations {
    runtimeClasspath.shouldResolveConsistentlyWith(compileClasspath)
}

As a result, both the runtimeClasspath and compileClasspath will resolve Groovy 3.0.1.

The relationship is directed, which means that if the runtimeClasspath configuration has to be resolved, Gradle will first resolve the compileClasspath and then "inject" the result of resolution as strict constraints into the runtimeClasspath.

If, for some reason, the versions of the two graphs cannot be "aligned", then resolution will fail with a call to action.

Declaring consistent resolution in the Java ecosystem

The runtimeClasspath and compileClasspath example above are common in the Java ecosystem. However, it’s often not enough to declare consistency between those two configurations only. For example, you most likely want the test runtime classpath to be consistent with the runtime classpath.

To make this easier, Gradle provides a way to configure consistent resolution for the Java ecosystem using the java extension:

Example 8. Declaring consistency in the Java ecosystem
build.gradle.kts
java {
    consistentResolution {
        useCompileClasspathVersions()
    }
}
build.gradle
java {
    consistentResolution {
        useCompileClasspathVersions()
    }
}

Please refer to the Java Plugin Extension docs for more configuration options.