Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Dependencies and Repositories

Constraints, Platforms (BOMs) and Exclusions in Gradle

Control transitive dependencies with constraints, import a BOM with platform(), align versions, exclude unwanted modules and use capabilities, with runnable stand-ins.

The previous lesson showed that Gradle picks the highest version when several are requested. This lesson covers the cleaner tools for steering that process in a team setting: constraints that raise or limit versions without adding a dependency, platforms (BOMs) that align a whole family of libraries, and exclusions that cut off modules you do not want. You will also see where each tool belongs: application builds versus published libraries.

Gradle code is read-only; Java stand-ins demonstrate constraint and BOM logic.

Constraints

A constraint says "if this module ends up in the graph, then use at least (or exactly) this version". It does not add the module itself. That is the difference from a regular dependency.

Kotlin
dependencies {
    implementation("com.example:lib-a:1.0")

    constraints {
        implementation("com.example:json:1.5") {
            because("1.2 has a known security vulnerability")
        }
    }
}

If lib-a pulls in json:1.2, the constraint lifts it to 1.5. If nothing needs json, it is not added. The because(...) text appears in dependencyInsight, which is great documentation for the next person. Constraints in a published library are included in its metadata, so consumers benefit too. That makes them the right tool for libraries; force only affects your own build.

Constraints can use the same version syntax as dependencies:

Syntax Meaning
"1.5" prefer 1.5, but allow a higher version from elsewhere
{ strictly("1.5") } exactly 1.5, fail if the graph conflicts
{ require("1.5") } at least 1.5
"[1.2, 1.6)" a range (closed at 1.2, open at 1.6)
{ reject("1.4") } never use 1.4

Stand-in: a constraint lifts a transitive version

This program is not Gradle. It resolves a module by taking the highest requested version, where constraints count as requests only when the module is in the graph already.

Java Stand-in: constraints do not add modules

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.

json becomes 1.5, while yaml is never added: it only had a constraint.

Platforms and BOMs

Frameworks such as Spring, Jackson or Netty publish many modules that must use matching versions. A BOM (Bill of Materials) is a special POM that lists the right version of every module. In Gradle you import one with platform(...), and then declare the modules without versions:

Kotlin
dependencies {
    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.4.1"))
    implementation("org.springframework.boot:spring-boot-starter-web")      // no version
    implementation("com.fasterxml.jackson.core:jackson-databind")           // no version
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

A platform contributes constraints: the BOM's versions apply to whichever of those modules appear in the graph, including transitive ones. enforcedPlatform(...) makes them strict, overriding any other request (use it sparingly).

You can combine a platform with the version catalog:

TOML
[libraries]
spring-boot-bom = { module = "org.springframework.boot:spring-boot-dependencies", version = "3.4.1" }
jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind" }
Kotlin
dependencies {
    implementation(platform(libs.spring.boot.bom))
    implementation(libs.jackson.databind)
}

You can also build your own platform in a project with the java-platform plugin, to share an approved set of versions across an organization:

Kotlin
// platform/build.gradle.kts
plugins { `java-platform` }

dependencies {
    constraints {
        api("com.google.guava:guava:33.4.0-jre")
        api("org.slf4j:slf4j-api:2.0.16")
    }
}

Other projects then use implementation(platform(project(":platform"))).

Stand-in: a BOM supplies the versions

The stand-in lets you declare modules without a version; the BOM fills them in. A module missing from the BOM and without a version is an error, just as in Gradle.

Java Stand-in: versionless declarations resolved by a BOM

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.

Exclusions

Sometimes a transitive dependency is unwanted: a logging binding that conflicts with yours, an old XML parser, a library you replace. You can exclude it for one dependency:

Kotlin
dependencies {
    implementation("com.example:lib-a:1.0") {
        exclude(group = "commons-logging", module = "commons-logging")
    }
    implementation("com.example:lib-b:2.0") {
        isTransitive = false          // ignore ALL of lib-b's own dependencies
    }
}

Or for a whole configuration:

Kotlin
configurations.all {
    exclude(group = "org.slf4j", module = "slf4j-log4j12")
}

Cautions:

  • An exclusion removes the module from the graph everywhere that rule applies. If something really needs the module, it fails at run time with ClassNotFoundException.
  • Exclusions are not part of a library's published constraints in the same way; prefer fixing the cause (a capability conflict or a platform) when you can.
  • isTransitive = false is blunt. Prefer targeted excludes.

Capabilities

Some modules provide the same functionality under different names (several SLF4J bindings, two Guava forks). Gradle's capabilities let a module declare what it provides, so Gradle can detect that two jars conflict even though their names differ, and you can choose with a rule:

Kotlin
configurations.all {
    resolutionStrategy.capabilitiesResolution.withCapability("com.google.collections:google-collections") {
        selectHighestVersion()
    }
}

You will rarely write capability rules, but you will see capability conflict errors, which tell you exactly which two modules clash.

Where to use which tool

Goal Tool
Align a framework's modules platform(...) (BOM)
Set a minimum or banned version without adding the module constraints { }
Fail on any other version strictly(...) or enforcedPlatform
Remove an unwanted transitive module exclude(...)
Two modules that provide the same thing capabilities
Pin the exact graph for reproducibility dependency locking

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between a constraint and a regular dependency?

    Constraints adjust versions of modules that are in the graph. They never add a module by themselves.
  2. 2. What does implementation(platform("x:bom:1.0")) do?

    A platform contributes version constraints. You still declare which modules you actually use.
  3. 3. What is a risk of excluding a transitive dependency?

    Removing a module that is really used leads to ClassNotFoundException or NoSuchMethodError when the code runs.
  4. 4. Why are constraints better than force for library authors?

    force only affects the build where it is written. Constraints travel with the published module.

Summary

  • Constraints raise, limit or reject versions of modules that are already in the graph, and never add modules.
  • platform(...) imports a BOM as constraints so you can omit versions; enforcedPlatform(...) makes them strict.
  • The java-platform plugin lets you publish your own organization's approved versions.
  • exclude(...) and isTransitive = false remove unwanted modules, at the risk of run-time errors.
  • Capabilities detect conflicts between modules that provide the same thing.
  • Prefer constraints and platforms to force, and document choices with because(...).

Next: Gradle Plugins: What They Are and How to Apply Them