Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 41 ยท Dependencies

Managing Versions: dependencyManagement and BOMs

Control library versions in one place with dependencyManagement, import-scope BOMs like Spring Boot and Jackson, version properties and the enforcer convergence rule.

As a project grows, the same libraries show up again and again. A multi-module build may use Jackson in five modules. A family of libraries (Jackson has a dozen artifacts) must use the same version to work together. If every <dependency> carries its own <version>, the numbers drift apart, and one day a build resolves two different versions of the same library.

Maven's answer is to separate what versions to use from what to depend on. The <dependencyManagement> section holds the first. The <dependencies> section holds the second. In this lesson you will learn how they interact, how a BOM (bill of materials) imports a whole set of tested versions at once, and how to make the build fail when versions disagree.

Maven itself cannot run in your browser, so all POM and command snippets are read-only. The runnable Java programs are stand-ins that apply the same rules to small, made-up libraries. They are teaching models, not Maven's resolver.

dependencies versus dependencyManagement

Compare these two blocks:

XML
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.19.2</version>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <!-- no version: taken from dependencyManagement -->
  </dependency>
</dependencies>

The first block does not add anything to your classpath. It is a table of defaults: "whenever this artifact is used here, this is the version (and scope, and exclusions)". The second block does add the library, and because the version is missing, Maven looks it up in the table.

Two sections, two jobs

dependencyManagement A table of versions. Adds nothing by itself.
dependencies The libraries you actually use.

Management decides how. Dependencies decide what.

1 / 2

There is one more rule, and it is the important one: managed versions also apply to transitive dependencies. If lib-d asks for x 1.0 but your management table says x 2.0, you get x 2.0, even though mediation would have picked something else. This is the clean replacement for the tricks from Transitive Dependencies and Mediation, where you re-declared a library or reordered dependencies to win a tie.

For your own direct dependencies, a version written in the <dependency> still beats the managed one. In practice you leave direct versions out, so the question does not arise.

Version properties

When one version number is repeated (for example, for all Jackson modules), give it a property:

XML
<properties>
  <jackson.version>2.19.2</jackson.version>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>${jackson.version}</version>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-core</artifactId>
      <version>${jackson.version}</version>
    </dependency>
  </dependencies>
</dependencyManagement>

Properties are explained in Properties and Build Settings. A property also lets someone override a version from the command line (-Djackson.version=2.19.3) when testing an upgrade, though a build that depends on such flags is harder to reproduce.

BOMs: import a whole set of versions

Writing every version yourself does not scale. Big projects publish a BOM (bill of materials): a POM with packaging pom that contains nothing except a <dependencyManagement> section listing tested, compatible versions. You import it with the special import scope:

XML
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson</groupId>
      <artifactId>jackson-bom</artifactId>
      <version>2.19.2</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Now every Jackson artifact can be declared without a version, and they all line up. The same technique is used by Spring Boot, whose BOM manages hundreds of libraries:

XML
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.5.6</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Two things must both be present for an import: <type>pom</type> and <scope>import</scope>, and the dependency must sit inside <dependencyManagement>. An import dependency in the plain <dependencies> section does not work.

Spring Boot also offers spring-boot-starter-parent, a parent POM that includes the same management plus plugin defaults. If your project can have that parent, the parent is the shortest route. If it already has another parent (a company POM, say), importing the BOM is the way to get the versions anyway. You will see parent POMs in Parent POMs and the Effective POM.

Precedence rules

When several sources manage the same artifact, Maven picks one by these rules:

  1. A version in your own <dependencyManagement> entry beats anything imported.
  2. Among imported BOMs, the first one declared wins.
  3. A BOM's own management never changes versions you wrote on a direct dependency.

That first rule gives you the standard way to override one library inside a BOM: write that single dependency in your own management section, above or below the import.

XML
<dependencyManagement>
  <dependencies>
    <!-- Local override: wins over the imported BOM -->
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.19.3</version>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.5.6</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

One detail catches people: with the parent approach, overriding a BOM property such as a version property in your own <properties> works. With an import, properties of the imported BOM are not inherited, so you override by listing the artifact, as above.

A managed-version resolver

The program below is a small model of this behavior. A resolver reads the declared dependencies; any without a version are filled from the management table; managed versions override transitive requests. It uses the same breadth-first mediation as the previous lesson, with the management step added. Compare scenario 1 (no management) with scenario 2.

Java Managed versions in a resolver

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.

Scenario 4 reproduces a very common error message: if a dependency has no version and no management entry supplies one, Maven stops with 'dependencies.dependency.version' for ... is missing.

BOM precedence in code

The second program applies the precedence rules to three management tables: your own, and two imported BOMs. It prints the merged table together with the source of each entry. Swap the order of the two BOMs and run it again to see rule 2 in action.

Java Local management beats BOMs, first BOM beats second

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.

Make the build catch disagreements

Management removes most conflicts, but it cannot tell you about the ones you did not manage. The Maven Enforcer Plugin can make the build fail when the dependency tree contains the same library in more than one version:

XML
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-enforcer-plugin</artifactId>
  <version>3.6.1</version>
  <executions>
    <execution>
      <id>enforce-versions</id>
      <goals>
        <goal>enforce</goal>
      </goals>
      <configuration>
        <rules>
          <dependencyConvergence/>
        </rules>
      </configuration>
    </execution>
  </executions>
</plugin>

With dependencyConvergence, any artifact that is requested at two different versions in the tree fails the build, even if mediation could pick one. That is strict, and it forces you to decide. A gentler rule is requireUpperBoundDeps, which only fails if mediation would pick a lower version than another path requested, the situation that most often causes NoSuchMethodError. You will study the symptoms in Diagnosing Dependency Conflicts.

Habits that scale

  • Put shared versions in one place: the parent POM or a BOM of your own.
  • In child modules, write dependencies without versions wherever the parent manages them.
  • Prefer importing a BOM over copying its versions by hand.
  • Use properties for versions that are repeated or that you need to bump together.
  • Add the enforcer rules early. It is much easier to start strict than to clean up later.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does an entry in dependencyManagement do by itself?

    dependencyManagement is a table of defaults. A library is only used when it also appears in dependencies (directly or transitively).
  2. 2. Which two settings are needed to import a BOM?

    A BOM is a pom-type artifact, and the import scope merges its dependencyManagement into yours. It only works in the dependencyManagement section.
  3. 3. A library you use asks for x 1.0, but your dependencyManagement says x 2.0. Which version is on the classpath?

    Managed versions override the versions requested transitively, which is what makes dependencyManagement the clean way to pin a library.
  4. 4. You import two BOMs that both manage commons-io, and you have no local entry. Which version wins?

    For imports, the first declaration wins. A local dependencyManagement entry beats both.
  5. 5. What does the enforcer rule dependencyConvergence do?

    It forces you to resolve disagreements explicitly, usually with dependencyManagement, instead of letting mediation decide silently.

Summary

  • dependencyManagement sets default versions, scopes and exclusions. It adds no libraries by itself.
  • Managed versions apply to transitive dependencies, so they replace mediation tricks as the way to pin a library.
  • A BOM imported with type pom and scope import brings in a tested set of versions at once.
  • Your own management entry beats imports, and the first imported BOM beats later ones.
  • Version properties keep repeated numbers in one place.
  • The enforcer's dependencyConvergence or requireUpperBoundDeps rules make hidden conflicts fail the build.

Next: Diagnosing Dependency Conflicts