Understanding pom.xml in Spring Boot – A Complete Guide

Published: 2025 • Java, Spring Boot, Maven, Project Setup

What is Maven?

Apache Maven is a powerful build automation tool used primarily for Java projects. It uses an XML file called pom.xml (Project Object Model) to manage:

• Dependencies – Libraries your project needs (like Spring Boot)
• Build lifecycle – Compile, test, package, and deploy automatically
• Plugins – Extend functionality (e.g., Swagger, Docker)

Maven ensures that your build process is repeatable, platform-independent, and versioned.

What is pom.xml?

The pom.xml file is the core of a Maven project. It describes your project structure, configuration, libraries, plugins, and goals. Without it, Maven won’t know how to build or run your application.

A basic Spring Boot project typically includes:

• Project identifiers (groupId, artifactId, version)
• Spring Boot starter dependencies
• Java version and build settings
• Plugins to execute the app or generate documentation

Maven Build Lifecycle Explained

Maven runs through a lifecycle of build phases. Here’s the most common ones:

• validate: Verify the project is correct
• compile: Compile the source code
• test: Run unit tests
• package: Create a JAR or WAR
• verify: Check package meets quality standards
• install: Install the package to your local repo
• deploy: Push to a remote repository (e.g., Nexus)

When you run mvn clean install, Maven goes through all these steps from start to finish.

How Maven Downloads Dependencies

When you define a dependency in pom.xml, Maven:

1. Checks your local cache: ~/.m2/repository
2. If missing, it fetches from a remote central repository (like Maven Central)
3. Saves it locally for future builds

This process ensures that once downloaded, your build doesn’t require internet again (unless versions change).

What is the parent Tag in pom.xml?

In Maven, a <parent> tag allows you to inherit configuration from another project’s pom.xml. This is very useful for:

• Sharing common settings across modules
• Centralizing plugin versions and configurations
• Getting predefined defaults like in Spring Boot

In Spring Boot, the recommended parent is:

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>2.7.13</version>
</parent>

This gives you:

• Default dependency versions
• Preconfigured plugins (like Spring Boot plugin)
• Useful properties (e.g., Java version, encoding)

pom.xml Without parent Tag

If you remove the parent section, you lose all default settings. This means:

• You must define all plugin versions manually
• You may run into missing or conflicting dependencies
• Spring Boot might not package or run as expected

Example of a minimal standalone POM (not recommended for beginners):

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>myapp</artifactId>
  <version>1.0.0</version>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
      <version>2.7.13</version>
    </dependency>
  </dependencies>
</project>

As you can see, managing versions manually can get complex quickly, especially as your project grows.

Understanding Key Tags in pom.xml

Let's break down every important tag used in a pom.xml file and what role each plays in your Spring Boot Maven project.

<groupId>

This defines your project's unique group or namespace — usually your reverse domain name.

Example: com.example

It's like your company's unique identifier for the codebase, ensuring the artifact name doesn't collide with others.

<artifactId>

This is the name of the artifact (JAR or WAR) Maven will build.

Example: user-service or springboot-api

When you package the project, the resulting file will be something like springboot-api-0.0.1-SNAPSHOT.jar.

<version>

This denotes the current version of your application or module.

Example: 1.0.0 or 0.0.1-SNAPSHOT

• SNAPSHOT versions are still in development
• Release versions are considered stable

<packaging>

Specifies whether the output is a jar, war, or pom.

Default: jar

In Spring Boot projects, we usually use jar because Spring Boot can embed a Tomcat server.

<properties> – Configuring Java Version and More

The <properties> section defines reusable variables across your project and influences plugin behavior.

<properties>
    <java.version>1.8</java.version>
    <spring.boot.version>2.7.13</spring.boot.version>
</properties>

• java.version: Tells Maven which Java compiler version to use
• spring.boot.version: Can help in referencing this value in plugin or dependency versions

<build> – Plugins and Build Behavior

The <build> section configures how the project is built, including what plugins to run during lifecycle phases.

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
  </plugins>
</build>

spring-boot-maven-plugin:

• Allows you to run your app via mvn spring-boot:run
• Enables fat JAR creation with embedded server
• Resolves runtime dependencies into the JAR

Multi-Module Projects with <modules>

If you're working in a large monorepo or enterprise setup, you might use Maven's multi-module capabilities.

Your main pom.xml (known as parent POM) will look like:

<packaging>pom</packaging>
<modules>
  <module>user-service</module>
  <module>order-service</module>
</modules>

Each subdirectory will contain its own pom.xml with a <parent> reference to the root POM.

Advantages of multi-module setup:

• Centralized dependency and plugin management
• Shared versioning across modules
• Independent testing/building of submodules

Tip: Override Parent Versions

If you use a <parent> but want to override a version (e.g., Java 17 instead of 1.8), you can simply redefine it in <properties>:

<properties>
  <java.version>17</java.version>
</properties>

Managing Versions with <dependencyManagement>

The <dependencyManagement> section allows the parent POM to control dependency versions across child modules. Instead of repeating the same version number everywhere, you can centralize it like this:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
      <version>2.7.13</version>
    </dependency>
  </dependencies>
</dependencyManagement>

Then in child POMs, you can declare the dependency without a version:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

Adding Test Dependencies

To enable JUnit and Mockito for writing unit tests, use the following:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>

This starter includes JUnit, AssertJ, Mockito, Hamcrest, and Spring Boot test tools out of the box.

Popular Plugins to Consider

Here are some commonly used Maven plugins to enhance your Spring Boot builds:

• Lombok Plugin

  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
  </dependency>

• Javadoc Plugin

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
  </plugin>

• Docker Plugin

  <plugin>
    <groupId>com.spotify</groupId>
    <artifactId>docker-maven-plugin</artifactId>
    <version>1.2.2</version>
  </plugin>

Common pom.xml Mistakes

• Missing <version> for a dependency when no <parent> or <dependencyManagement> is used
• Conflicting versions of the same dependency due to transitive imports
• Forgetting spring-boot-maven-plugin causes mvn spring-boot:run to fail
• Using a deprecated Java version (e.g., Java 6 or 7)

Quick Checklist for a Healthy POM

• Use Spring Boot’s parent for simplicity
• Declare proper groupId, artifactId, and version
• Lock your Java version using <properties>
• Include spring-boot-maven-plugin for easy builds
• Use <dependencyManagement> in parent POMs
• Clean with mvn clean before every full build

Final Thoughts

The pom.xml file is more than just metadata — it's the blueprint of your Spring Boot application's build and runtime behavior. Understanding it deeply allows you to resolve issues faster, scale projects better, and reduce redundant config across your modules.

By applying the practices in this article, you now have the foundation to configure enterprise-grade Java applications using Maven and Spring Boot.