Using Maven dependencyManagement with a BOM to enforce consistent versions

Using Maven dependencyManagement with a BOM to enforce consistent versions

When you have a multi‑module Maven build, you can avoid scattering version numbers across many pom.xml files by declaring the versions once in a dependencyManagement section and importing a Bill‑of‑Materials (BOM). Child modules then only need to list the dependency; Maven resolves the version from the inherited management section.

Worked configuration

<!-- parent/pom.xml -->
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>parent</artifactId>
  <version>1.0.0</version>
  <packaging>pom</packaging>
  <modules>
    <module>child-web</module>
  </modules>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-dependencies</artifactId>
        <version>3.3.0</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

<!-- child-web/pom.xml -->
<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0</version>
  </parent>
  <artifactId>child-web</artifactId>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
      <!-- no version; inherited from BOM -->
    </dependency>
  </dependencies>
</project>

Running mvn clean package from the parent directory resolves spring-boot-starter-web to version 3.3.0 in the child module.

Limits and common mistakes

• The BOM only controls versions of dependencies that are explicitly listed in it. Transitive dependencies that bring in conflicting versions are not overridden unless you add them to dependencyManagement or use <exclusion>.
• If a child module declares a version for a managed dependency, that explicit version wins over the BOM – a frequent source of drift when refactoring.
• The parent POM must have <packaging>pom</packaging> and be installed in the local repository (or available from a remote) before the child modules are built.
• When the BOM resides in a private repository, verify repository URLs and credentials in settings.xml; otherwise the build fails with a missing artifact error.
• Over‑reliance on a BOM can hide version mismatches in deep transitive trees; periodically run mvn dependency:tree or mvn help:effective-pom to inspect the resolved classpath.