Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 41 ยท The POM

Parent POMs and the Effective POM

Learn how Maven POM inheritance works: the parent element, the Super POM, relativePath, what children inherit, and how to inspect the result with help:effective-pom.

Every Maven project inherits from another project, whether you write <parent> or not. A team with twenty services does not want to copy the same Java version, plugin settings and dependency versions into twenty files; it puts them in one parent POM and lets every child inherit them.

This lesson explains how inheritance works, what is and is not inherited, and how to see the final merged result with the effective POM. As before, real mvn commands and POM files are read-only here, and the runnable TryIts are Java stand-ins that model the merge. They are simplified, not Maven's real code.

Inheritance has layers

Super POM Built into Maven. Every project has it.
Parent POM Your shared settings.
Child POM The project that overrides what it must.

Effective POM = all three merged.

1 / 2

The parent element

A child declares its parent with coordinates, like any other artifact reference.

XML
<project>
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>com.example</groupId>
    <artifactId>company-parent</artifactId>
    <version>3</version>
    <relativePath>../company-parent/pom.xml</relativePath>
  </parent>

  <artifactId>billing-service</artifactId>
</project>

Notice what is missing: the child has no groupId and no version. When they are omitted, they are taken from the parent, which keeps a group of projects in step. The artifactId is never inherited, because every project must be named individually.

The parent itself is an ordinary POM with <packaging>pom</packaging>, because it produces no JAR, only configuration.

XML
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>company-parent</artifactId>
  <version>3</version>
  <packaging>pom</packaging>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>25</maven.compiler.release>
  </properties>
</project>

relativePath

When Maven reads a child, it must find the parent POM. It checks, in order: the path in <relativePath> (default ../pom.xml, that is, the folder above), then the local repository, then remote repositories. A file found through relativePath is accepted only if its coordinates match the <parent> block; otherwise Maven warns and looks elsewhere.

Two practical cases follow from this.

  • The parent lives in a different folder: set relativePath to it.
  • The parent was published to a repository and is not on disk (as with Spring Boot's parent): write an empty element, <relativePath/>, so Maven does not waste time or print a warning looking in ../pom.xml.

The Super POM

Even a POM with no <parent> is not alone. Maven silently places the Super POM at the top of every chain. It is bundled inside Maven and supplies the conventions you have been relying on:

  • Maven Central as the default repository and plugin repository.
  • The standard directories: src/main/java, src/test/java, src/main/resources, and output to target.
  • The default finalName of ${project.artifactId}-${project.version}.
  • Default settings for some core plugins.

This is the "convention over configuration" idea in code form. Your POM is short because most decisions were made for you by the Super POM, and you override only where you differ.

What a child inherits

Almost everything from the parent is inherited, including:

  • groupId, version (unless the child declares its own),
  • properties,
  • dependencies (every dependency listed directly in the parent is added to every child),
  • dependencyManagement and pluginManagement,
  • build settings, plugins and their configuration,
  • repositories, distributionManagement, organization, licenses and similar metadata.

A few elements are never inherited: artifactId, name, packaging (a child defaults to jar even if the parent is pom), the modules list and the parent element itself.

Anything in the parent's plain <dependencies> lands in every child, even those that do not need it. Put shared version numbers in <dependencyManagement> instead, which declares versions without adding anything. You will use that in Managing Versions.

How values are merged

Merging follows a few simple rules.

  1. A simple value in the child replaces the parent's: if both set <maven.compiler.release>, the child's wins.
  2. Properties are merged by name. The child keeps its own and adds the parent's missing ones.
  3. Dependencies are merged by key (groupId:artifactId:type:classifier). A dependency declared in both appears once, with the child's details.
  4. Plugin configuration is merged element by element, recursively. A child can add or override one setting without repeating the rest.
  5. Lists of plugins and executions are combined, with the parent's entries first.

You can change how nested configuration merges with the attributes combine.children="append" and combine.self="override". They are advanced tools, and rarely needed.

A merge simulator

The stand-in below uses plain Java maps to apply rules 1 to 3: a Super POM layer, a parent layer and a child layer, merged from top to bottom. The real Maven works on a full object model, so this is only an illustration of the idea.

Java Merging Super POM, parent and child (stand-in)

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.

The result shows the child's release (25) replacing the parent's 21, the SLF4J version taken from the child, Guava added, the parent's encoding inherited from company-parent, and packaging back at jar because it is not inherited.

Looking at the effective POM

You do not have to merge in your head. Maven can print the final result:

Terminal
mvn help:effective-pom

The output is the full POM after inheritance and interpolation: Super POM defaults, parent settings, your own settings, with every ${...} replaced. It also tells you where each section came from, using XML comments. Write it to a file for easier reading:

Terminal
mvn help:effective-pom -Doutput=effective.xml

Use it whenever a build behaves in a way the visible pom.xml cannot explain: a plugin version nobody wrote, a repository that appears from nowhere, a property with an unexpected value. The related mvn help:effective-settings prints the merged settings.xml, and mvn help:all-profiles lists the available profiles.

flowchart TB
    S["Super POM (built in)"] --> P["company-parent"]
    P --> C["billing-service"]
    C --> E["Effective POM"]

Each layer overrides the one above it; Maven resolves the final model before it runs anything.

A second stand-in: finding the source of a value

The effective POM is only useful if you can tell where a surprising value came from. The stand-in below walks the chain from the child upward and reports the first layer that defines a property.

Java Which layer defined this value? (stand-in)

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.

In real Maven this question is answered by reading the comments in the effective POM output, or by running with -X to see more detail.

Inheritance versus aggregation

Inheritance (<parent>) is often confused with aggregation (<modules>). They are separate ideas.

  • Inheritance shares configuration: a child points up to a parent.
  • Aggregation builds several projects together: an aggregator points down to its modules.

One POM can do both, and in many multi-module projects the root POM is both the parent and the aggregator, but neither requires the other. Multi-Module Builds and the Reactor goes deeper.

Best practices

  • Keep a company or project parent small: Java settings, encoding, plugin versions, and dependencyManagement.
  • Pin plugin versions in pluginManagement so builds are repeatable.
  • Prefer an explicit <relativePath/> for parents that come from a repository.
  • Use help:effective-pom before you ask "why does Maven do this?".

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A child POM declares only artifactId and a parent. What groupId and version does the child use?

    When groupId and version are omitted in the child, Maven takes them from the parent. artifactId, by contrast, must always be given.
  2. 2. Which element is NOT inherited from a parent POM?

    packaging, artifactId, name, modules and the parent element itself are not inherited. A child defaults to packaging jar even if the parent says pom.
  3. 3. Why would you write <relativePath/> (empty) in a parent element?

    An empty relativePath disables the file-system lookup. It is used for parents that come from a repository, as with the Spring Boot parent.
  4. 4. Which command shows the POM after inheritance and interpolation?

    help:effective-pom prints the merged model: Super POM, parents and your POM, with all properties resolved.

Summary

  • Every POM inherits from a parent chain that ends at the built-in Super POM, which holds Maven's conventions.
  • A child omits groupId and version to take the parent's; artifactId, name, packaging and modules are never inherited.
  • Child values override parents; properties merge by name and dependencies by groupId and artifactId.
  • relativePath tells Maven where to find the parent on disk; <relativePath/> skips that lookup.
  • mvn help:effective-pom prints the final merged POM, and is the first tool to try when a build surprises you.
  • Inheritance shares configuration; aggregation builds modules together. The merge demos above are stand-ins for the real model builder.

Next, learn what actually happens when you run a build: Lifecycles and Phases.