Introduction

In Maven, "parent POM" and "modules POM" are related ideas, but they are not the same concept. A parent POM is about inheritance of configuration. A POM with a modules section is about aggregation and build coordination. One file can play both roles, but you should understand them separately or multi-module builds become confusing very quickly.

What a Parent POM Does

A parent POM provides shared configuration that child projects inherit. Typical parent-level content includes:

• dependency versions in dependencyManagement
• plugin versions in pluginManagement
• shared properties
• repository and build settings

A child module points to the parent using the parent section.

1<parent>
2    <groupId>com.example</groupId>
3    <artifactId>platform-parent</artifactId>
4    <version>1.0.0</version>
5</parent>

That tells Maven to inherit configuration from the parent POM.

What a Modules POM Does

A POM with a modules section is an aggregator. Its job is to tell Maven which subprojects belong to the build.

1<packaging>pom</packaging>
2<modules>
3    <module>core</module>
4    <module>api</module>
5    <module>web</module>
6</modules>

When you run Maven at this top level, it builds the listed modules in the right order.

So aggregation is about "which projects are in this build." Inheritance is about "which configuration do these projects share."

One POM Can Be Both

A common structure is a top-level POM that acts as both:

• the parent for child modules
• the aggregator that lists those modules

1<project>
2    <modelVersion>4.0.0</modelVersion>
3    <groupId>com.example</groupId>
4    <artifactId>app-parent</artifactId>
5    <version>1.0.0</version>
6    <packaging>pom</packaging>
7
8    <modules>
9        <module>core</module>
10        <module>api</module>
11    </modules>
12
13    <dependencyManagement>
14        <dependencies>
15            <dependency>
16                <groupId>org.slf4j</groupId>
17                <artifactId>slf4j-api</artifactId>
18                <version>2.0.13</version>
19            </dependency>
20        </dependencies>
21    </dependencyManagement>
22</project>

That is common, but it is a design choice, not a Maven rule.

They Can Also Be Separate

Large organizations sometimes separate the roles.

For example:

• one corporate parent POM provides standard plugin and dependency management
• another aggregator POM collects the modules for a particular build

This is useful when many projects share the same parent but are not part of the same multi-module reactor build.

How Child Modules Usually Look

A child module typically inherits from the parent and defines its own artifact-specific dependencies.

1<project>
2    <modelVersion>4.0.0</modelVersion>
3
4    <parent>
5        <groupId>com.example</groupId>
6        <artifactId>app-parent</artifactId>
7        <version>1.0.0</version>
8    </parent>
9
10    <artifactId>core</artifactId>
11
12    <dependencies>
13        <dependency>
14            <groupId>org.slf4j</groupId>
15            <artifactId>slf4j-api</artifactId>
16        </dependency>
17    </dependencies>
18</project>

The dependency version can be omitted because the parent manages it.

dependencyManagement Is Not the Same as Modules

Another source of confusion is mixing up dependency inheritance with project aggregation. The modules section tells Maven which subprojects participate in the reactor build. dependencyManagement tells child projects which dependency versions to inherit when they declare those dependencies.

Those are different jobs:

• 'modules controls build composition'
• 'dependencyManagement controls version alignment'

Understanding that distinction helps explain why a parent POM often contains both sections even though they solve separate problems.

The Core Difference

The cleanest summary is:

• parent POM: controls inheritance
• modules POM: controls aggregation

That is why a POM can list modules without being their parent, and a POM can be a parent without listing modules at all.

Common Pitfalls

• Assuming any POM with modules automatically acts as the parent for those modules.
• Assuming any parent POM must also aggregate modules in the same repository.
• Putting dependency versions directly in each child instead of centralizing them in dependencyManagement.
• Confusing dependencyManagement inheritance with actual dependency inclusion.
• Forgetting that packaging should usually be pom for parent or aggregator POMs.

Summary

• A parent POM is for inheritance of shared Maven configuration.
• A modules POM is for aggregating subprojects into one reactor build.
• One top-level POM can serve both roles, but they are still separate concepts.
• Child modules usually reference the parent with the parent element.
• Understanding inheritance versus aggregation makes multi-module Maven builds much easier to reason about.