Maven 4: What’s New

For twenty years the POM has served two audiences. Maven itself reads it to build the project (plugins, properties, profiles, modules). Everybody who depends on the artifact (other Maven projects, Gradle, IDEs, scanners, Maven Central) reads the very same file from the repository to learn its dependencies. Because the whole ecosystem parses that file, its schema, model version 4.0.0, could not change without breaking someone. Maven 4 breaks that deadlock by treating them as two documents: the build POM in your source tree may use the new model version 4.1.0, and what is installed and deployed for consumers is a consumer POM that still says 4.0.0. Most of what is new is either a consequence of that split or something the split now permits.

The section Build POM and consumer POM below shows the files this produces.

Maven 4 needs Java 17 or newer to run. Compiling for an older release is unchanged: you still choose it with the compiler plugin (maven.compiler.release) or a toolchain, see Compiling & Toolchains. rc-7 started on a JDK 17 (JetBrains Runtime) without problems:

(The Default locale, OS name and later lines were left out.) Java 17 became the minimum with Maven 4.0.0-alpha-13, in March 2024. CI images that still run Maven on Java 8 or 11 must move; the project being built does not have to.

Source: What’s new in Maven 4: Required Java version

A POM whose root element is declared in the namespace http://maven.apache.org/POM/4.1.0 is a model 4.1.0 POM. Maven 4 still builds every 4.0.0 POM unchanged, so nothing forces you to move. Maven 3 cannot read 4.1.0, and the failure is confusing, because it complains about the first new attribute it meets rather than about the version. This is the tidepool parent POM used below on Maven 3.10.0 (3.9.16 prints the same):

(Only the first lines are shown.) The practical rule: the repository that holds a 4.1.0 build POM can only be built with Maven 4. What you publish does not have this problem, because consumers get the 4.0.0 consumer POM. The element-by-element list of what 4.1.0 adds is on Maven 4: POM Model & Consumer POM.

Source: What’s new in Maven 4: Model version 4.1.0

Since Java 9 the word "module" also means a Java Platform Module System module, and a Maven "module" is merely a project in a subdirectory. Maven 4 therefore renames the concept: model 4.1.0 has a <subprojects> element (with <subproject> children) analogous to <modules>, which stays usable but is deprecated. A project with subprojects is a multi-project build, one without is a single-project build. The reactor itself is unchanged, see Multi-Module Builds & the Reactor.

The tidepool parent POM below has no list at all:

When a parent has pom packaging and neither <subprojects> nor <modules>, Maven 4 adds every direct subdirectory that contains a pom.xml. Each subproject below inherits and depends without repeating coordinates (explained in Parent and version inference):

Running mvn clean verify on rc-7 found all three subprojects and ordered them from the dependencies:

(Only the reactor lines are shown; the ... marks the removed plugin output.) The same discovery is also what makes <parent/> find the parent: with an empty <parent/> Maven looks for a pom.xml in ...

Source: What’s new in Maven 4: Modules are now subprojects and Subprojects discovery

Maven 4 finally ships MNG-624, opened in 2005: with model 4.1.0 you need not repeat the parent version, nor the version of a dependency on another project of the same reactor. You can write <parent><relativePath>..</relativePath></parent>, the shorthand <parent/> (parent in ..), or just leave out <version>, <groupId> or <artifactId> of the parent. A dependency on a sibling needs only groupId and artifactId. The tidepool-engine POM above does exactly this, and the dependency on tidepool-model has no version. The result is that a version bump is a change in one file.

The inferred values are written back into the consumer POM, so readers never see the shorthand (see Build POM and consumer POM).

Source: What’s new in Maven 4: Automatic versioning and Parent inference

Maven 3.5.0 added ${revision}, ${sha1} and ${changelist} as version placeholders, but publishing a POM that still contained the placeholder broke consumers, so everybody added the Flatten Maven Plugin. In Maven 4 the consumer POM is generated with the placeholder replaced, and any property name works, not just the three predefined ones. The tidepool parent above has <version>${revision}</version> and no flatten plugin; mvn install on rc-7 produced a consumer POM with the real version (see the next section). Define the property on the command line (-Drevision=4.0.1), in .mvn/maven.config, or in the root or parent POM. The full treatment, including the Maven 3 workflow it replaces, is on Maven CI-Friendly Versions.

Source: What’s new in Maven 4: Full support of CI-friendly variables

mvn install on rc-7 put four files for each subproject into the scratch local repository (shown here for tidepool-engine):

(_remote.repositories was left out.) The -build.pom is the file from your source tree, installed with the classifier build, and it is the only one that is model 4.1.0. The plain .pom, the one every consumer reads, is generated:

The model version is 4.0.0, the <parent/> shorthand has become a real parent with a version, and the dependency has its version. By default the consumer POM keeps the parent reference, which is why the parent POM is installed too. Setting the user property maven.consumer.pom.flatten=true goes further and produces a flattened POM. The same build with -Dmaven.consumer.pom.flatten=true:

The parent is gone and the group and version are taken from it. Flattening is off by default because it changes which dependencies are listed (only compile and runtime ones, and managed versions only when used); the official comparison table says that the consumer POM keeps third-party dependency information, repository information, project information and the deployment information, while POM properties and plugin configuration exist only in the build POM. Where the consumer POM cannot be expressed in 4.0.0 (a condition-based profile, see Profiles: optional ids and condition activation), Maven warns and may publish a 4.1.0 consumer POM. Pitfalls and the Mermaid flow of how the model builder produces each file are on Maven 4: POM Model & Consumer POM.

Source: What’s new in Maven 4: Consumer POM and Comparing build POM and consumer POM

Maven always needed to know where the project root is (to find .mvn/maven.config, the parent, shared files). Until now the only way to tell it was a .mvn directory, and there was no official property to refer to that directory from a POM (people used internal properties instead, now removed or deprecated, see MNG-7038). Maven 4 adds a boolean root attribute on <project> (model 4.1.0 only; default false), and three properties:

${basedir} is the base directory of each individual subproject, as before. When no root can be found rc-7 does not stay silent: on a single-project build without .mvn and without the attribute, it prints this warning on the first line of output:

The new plugin generation depends on it. The 4.x compiler plugin refuses to run without a root (see Declaring source directories with sources), so a .mvn directory or root="true" is part of the move to Maven 4 even for projects that do not need the properties.

Source: What’s new in Maven 4: Declaring the root directory and directory properties

Maven 3 has <sourceDirectory> and <testSourceDirectory>, one directory each, so a second source root needed the Build Helper plugin. Maven 4 adds <build><sources>, a repeatable <source> with a <scope> (main or test), a <directory> and, in the compiler plugin’s documentation, include and exclude filters and per-source target releases for multi-release projects and the module source hierarchy. A scratch project with two main source roots:

With the 3.x compiler plugin line, 3.16.0, both directories were compiled (Compiling 2 source files). The 4.x line, 4.0.0-beta-5, which is the first to read the new element natively, produced both classes (A.class and Extra.class) too, but only after the build had a root directory. In the same project without root="true" (and without .mvn):

Note that the 4.x plugin lines (compiler 4.0.0-beta-5, install and deploy 4.0.0-beta-3, resources 4.0.0-beta-2) are the ones that use the new Maven API, and they only run on Maven 4.

Source: What’s new in Maven 4: New way to declare source directories

A dependency’s <type> selects the artifact kind. jar stays the default, and Maven 4 adds types that say where the JAR goes:

The article warns that, in October 2025, only the compiler plugin (4.0.0-beta-3 and later) honours them; other plugins will follow.

Maven 4 also adds a dedicated bom packaging, so a bill of materials is no longer a parent POM in disguise. It exists only in the build POM (model 4.1.0); Maven generates a Maven 3 compatible consumer POM. This POM, built with mvn install on rc-7 (the .mvn directory is present, and the install plugin version was not pinned):

installed this consumer POM, in which bom became pom:

Two related details from the article: in model 4.1.0 an import-scope BOM can be selected with <classifier> and its dependencies can be excluded with <exclusions>, and a BOM imported from the same reactor draws a warning, because the team recommends importing only BOMs that are published before the build. For the Maven 3 mechanics see Dependency Management & BOMs.

Source: What’s new in Maven 4: New artifact types and New packaging type: bom

The 4.0.0 consumer POM must stay XML, but the build POM may not have to. Maven 4 has a ModelParser service provider interface (MNG-7836) that a core extension can implement to read the build POM in another syntax. The article names the Apache Maven Hocon Extension as one of the first users. Core extensions are loaded from .mvn/extensions.xml, see Maven Extensions. Nothing in this page was run against a custom parser.

Source: What’s new in Maven 4: Alternate POM syntaxes

Resume. In Maven 3, a failing subproject B that depends on A produced the advice to resume from B, which then failed at once because A was no longer built. In Maven 4, -r or --resume resumes from the subproject that failed last time, and the reactor remembers the subprojects that succeeded. The reactor summary of a failing build points at it. A Broken.java was added to tidepool-cli:

After deleting the file, mvn -r verify (the output was filtered to the relevant lines):

Maven 3.10.0 does not know the option: mvn -r verify ends with Unable to parse command line options: Unrecognized option: -r. The long-standing bug that made -am ignore the resumed subprojects (MNG-6863) is fixed, and the reactor is aware of builds started from a subdirectory (MNG-6118). The article’s advice follows from this: use mvn verify for everyday builds, not mvn clean install.

All or nothing deploy. In Maven 3, a failure late in the reactor left the early subprojects installed or deployed. The article says Maven 4 changes the deployAtEnd default to true. That default is a property of the plugin, not of the core, and the experiment showed it: with the 3.x install and deploy plugins (3.2.0) pinned, the failing build above still installed tidepool-parent, tidepool-model and tidepool-engine into a fresh local repository, and the mvn deploy to a file:// repository (with -DaltDeploymentRepository) wrote 42 files before tidepool-cli failed. With the 4.x plugin line (4.0.0-beta-3 for install and deploy) in the parent:

and neither the scratch local repository nor the file:// repository received a single file. On success the same plugins installed all four subprojects after the last jar goal (Installing ... lines come after install:4.0.0-beta-3:install of the last subproject). So "deploy only if everything built" needs both Maven 4 and the 4.x install and deploy plugin versions: pin them in pluginManagement. Section Where install, deploy and release are covered says where this is treated in depth.

Further, all subprojects now get the same timestamp in their SNAPSHOT file names (MNG-6754).

Source: What’s new in Maven 4: Reactor improvements and fixes and Further improvements

The mechanics of install, deploy and distributionManagement are on Install, Deploy & Distribution Management and the release process on Releasing. The release-candidate status of Maven 4 matters there: the release plugin line for Maven 4 was not part of this page’s runs, so use Maven 3.10 or 3.9 for releases until you have tested your own flow.

Warnings that nobody reads become errors with -fos WARN (long form --fail-on-severity WARN). The argument may be WARN, WARNING or ERROR; any other value is rejected. A project whose POM does not pin the compiler and resources plugins gets a warning on rc-7:

The exit code was 1; with -fos ERROR the same build succeeded with exit code 0. A bad value:

The warning shown is the other point of the super POM upgrade: its default plugin versions are new in Maven 4, so a build that relied on them may change behaviour, and rc-7 now warns that you do. Pin every plugin version. Maven 3.10.0 has no such option: --fail-on-severity is Unrecognized option, and the short -fos WARN is silently read as -f os WARN, the file os, with the error Non-readable POM /work/classic/os. This option is the quickest way to keep a Maven 4 migration clean in CI (see Migrating to Maven 4).

Source: What’s new in Maven 4: "Fail on severity" parameter

A missing profile is now an error. In Maven 3 -Pnonexistent printed a warning and carried on, which hid typos. Maven 4 stops. Run on the same 4.0.0 project with the three releases (Maven 3.9.16 and 3.10.0 print the same):

(The Maven 3 warning is printed twice, at the start and at the end of the build; one is shown.) Prefix the id with ? to get the tolerant behaviour back. The command needs quoting in shells where ? is a wildcard:

Condition-based activation. In model 4.1.0 <activation> accepts a <condition> element holding an expression. The functions present in the rc-7 implementation are length, upper, lower, substring, indexOf, contains, matches, not, if, exists, missing and inrange, with the logical operators of the expression language. An unknown function is a model error:

(Only the first of two identical lines is shown.) A profile that is active when a data directory exists and the running Java is 17 or newer:

With and without the directory (flavour has the default plain in <properties>):

(Both runs filtered to the relevant lines.) Maven 3.10.0 rejects the same POM with Malformed POM ... Unrecognised tag: 'condition'. The profile reference is on Maven Profiles. A profile that uses <condition> cannot be written in 4.0.0, so the published consumer POM may be 4.1.0 (Maven warns when that happens).

Source: What’s new in Maven 4: Improvements to profiles and Condition-based profile activation

The Maven 3 lifecycle is one ordered list of phases. Maven 4 defines it as a tree, which allows finer dependencies (a project can start once a dependency has reached the ready phase instead of finishing verify) and skipping steps (deploy without installing). For compatibility the default execution does not change; the tree is used by the opt-in builder: mvn -b concurrent .... Every phase has a before: and an after: hook, executions in the same phase can be ordered with [n], and two new phases, all and each, wrap a whole project and each phase of it. The deprecated pre-* and post-* names remain as aliases.

A scratch plugin binding to try the hooks, in tidepool-model (the antrun plugin with <echo>):

mvn compile -pl tidepool-model on rc-7 (plugin goals only):

(The [WARNING] prefix is how the antrun plugin prints its <echo>.) Two behaviour changes follow from the new hooks. First, Maven 4 always runs the after: hook of a phase it reaches, while Maven 3 ran a post-* phase only when the next phase ran or when you named it. The experiment bound the echo to post-clean in a 4.0.0 POM: mvn clean -pl tidepool-model printed nothing from it on Maven 3.10.0 and printed post-clean ran on rc-7. Second, binding to a pre-* or post-* phase now works as an alias, but the article warns against it, notably for plugins bound to a post-* phase whose pre-* counterpart does not exist.

An observation specific to rc-7 and the concurrent builder: with -b concurrent, the run of the same compile printed before:all, before:compile, the compiler and after:all, but neither resources:resources nor the two after:compile[n] executions. The build still reported success. Treat -b concurrent as experimental in the release candidate and compare the executed goals with those of the default builder before relying on it. An unknown builder id fails with BuilderNotFoundException. The phases, ordering and builder are explained on Maven 4: Lifecycle, and the Maven 3 lifecycle on Maven Build Lifecycle.

Source: What’s new in Maven 4: Lifecycle changes, Before- and after-phases and Behavioral change: phase execution scope

Maven 4 removes long-deprecated pieces, and a plugin that uses them stops working:

Writing plugins is on Writing Maven Plugins.

Source: What’s new in Maven 4: Maven plugins and Application maintenance

mvnenc and password encryption. Maven 3’s master-password mechanism was "obfuscation". Maven 4 replaces it with Maven Encryption, a command line tool mvnenc, which has these goals in rc-7:

It adds decrypt and supports external vaults. The command is also reachable as mvn --enc. The settings that use encrypted values are on settings.xml & Password Encryption; mvnenc init is interactive and was not run here.

Maven Resolver 2. The core ships Maven Artifact Resolver 2.0.23 (maven-resolver-impl-2.0.23.jar); Maven 3.10.0 ships 2.0.24, so Resolver 2 is not new compared with 3.10. What is new is that in Maven 4 the resolver is behind the Maven API and plugins do not call it directly. The rc-7 log line Loaded 24114 auto-discovered prefixes for remote repository central comes from it. See Maven Resolver.

mvnsh, the Maven Shell. mvnsh keeps one Maven process open for a session, which saves the JVM start and configuration load of every command. It is the single-process counterpart to the Maven Daemon (mvnd), see Build Performance: Cache, Parallel Builds & mvnd. Run without a terminal (printf — '-v\nexit\n' | mvnsh), it printed its banner and 4.0.0-rc-7 and then ended with a NullPointerException from the JLine terminal capability lookup, so the shell needs a real interactive terminal. It was not run interactively here.

mvnup, the Upgrade Tool. mvnup check reports what needs to change, and mvnup apply rewrites the POMs. --all (-a) means --model-version 4.1.0 --infer --model --plugins. On a copy of the 4.0.0 tidepool project (committed in a scratch git repository), mvnup -B check --all listed 13 strategies (excerpt):

mvnup -B apply --all then changed all four POMs (git diff --stat: 17 insertions, 32 deletions): namespace and schema to 4.1.0, <modules> to subprojects (or auto-discovery), parents shortened to the <parent> shorthand, post-clean to after:clean, and maven.compiler.release to a <sources><source><targetVersion>17</targetVersion></source></sources> block. That last change shows the one trap worth knowing: tidepool pins the 3.x compiler plugin 3.16.0, which does not read <sources>, so mvn verify on the upgraded project failed:

Review the diff and re-run the build after mvnup apply; with the 3.x compiler plugin keep maven.compiler.release, or move to the 4.x compiler plugin. The release notes of rc-7 list several mvnup fixes, so the tool is itself still moving. The step-by-step migration is on Migrating to Maven 4.

Source: What’s new in Maven 4: Maven plugins, security, and tools, Maven Upgrade Tool and Password Encryption (Maven 4)

Maven 4’s separation of build and published metadata is the model Gradle already has: its Gradle Module Metadata is published next to a POM and the build script is never published (see Comparing Ant, Maven & Gradle). Subprojects are the Gradle word as well. Apache Ant has neither a project model nor a lifecycle, so there is nothing to compare for the lifecycle tree. The migration page between tools covers moving between them.

The complete list of resolved issues is the issue overview linked from the article.