Maven Plugins & Their Configuration

Maven distinguishes two kinds of plugin, by where they are configured and when they run:

Some plugins are both (the catalogue below marks them B+R): Checkstyle, PMD, Javadoc and Dependency can run as a build goal that fails the build, and as a report on the site. See Site & Reporting for the reporting side.

Source: Maven: Available Plugins

The Ant counterparts are tasks and Antlibs (Antlibs & Namespaces); the Gradle counterpart is plugins, which add tasks and conventions (Gradle Plugins Overview). The big difference is that Maven plugins are written to a fixed contract: parameters are declared on the Mojo and documented in a generated help.

Most Maven plugins carry a help goal that prints a description of the plugin, its goals, and, with -Ddetail, every parameter with its default and its user property. It is the first thing to run for an unfamiliar plugin, and it always describes the exact version your build uses. For the JAR plugin in tidepool-model:

Source: Apache Maven JAR Plugin: jar:help

(The banner and build summary lines were removed.) jar:help ran the jar plugin’s own help goal, version 3.5.1, the version the project’s pluginManagement pins. To see the parameters of one goal, add -Dgoal= and -Ddetail. The output for the compiler plugin, filtered with grep to a few parameters:

(Whitespace trimmed; the real listing has dozens of parameters.) Each parameter has a name (what you write as an XML element in the POM), an optional default, and optionally a user property (what you can set with -D on the command line or in the POM’s <properties>). maven.compiler.release is the user property for the release parameter, which is why <maven.compiler.release>21</maven.compiler.release> in the parent POM configures the compiler. A parameter without a user property can only be set in the POM.

Source: Apache Maven Compiler Plugin: compiler:help, detail

The Help plugin’s own describe goal is the other half: it describes a plugin from the outside, with no need for the plugin to have a help goal, and it can describe a lifecycle phase:

-Dplugin= accepts a prefix, groupId:artifactId or groupId:artifactId:version; -Dgoal= narrows to one goal; -Dmedium and -Ddetail add detail; -Dcmd= takes a phase or a goal (see the lifecycle page). To see what a build actually resolved, rather than what a plugin could do, use mvn help:effective-pom (see Inheritance, Aggregation & the Effective POM) or run with -X as shown below.

Source: Maven guide: Help Goal

Source: Help plugin: help:describe

Configuration goes in a <configuration> element, either inside a <plugin> (applies to every execution of the plugin) or inside an <execution> (applies to that execution only). Each child element is named after a parameter. How the text is converted depends on the parameter’s Java type, which Maven’s configurator reads from the Mojo. The following scratch module, tidepool-conf-demo, configures a simple value, a list, a complex object, a map and a properties block in one build:

The versions of the two plugins come from the parent’s pluginManagement (below). mvn -B -X test prints, for each execution, the value Maven injected into each parameter. Filtered to the interesting lines:

The test in the module reads the two system properties and passes, so the map really reached the forked test JVM. (s) and (f) say how the value was injected (through a setter or straight into a field); they describe how the plugin author declared the parameter, not where the value came from.

The mapping rules, with the examples above:

Source: Maven guide: Configuring Parameters

Source: Maven guide: Mapping Complex Objects

Source: Maven guide: Mapping Maps

Source: Maven guide: Mapping Properties

An <execution> binds goals to a phase, with its own configuration. It has:

Multiple executions in one phase run in declaration order, parents first. Maven 4 (release candidate) adds explicit ordering with phase[200], which Maven 3 ignores silently; the lifecycle page has a run of both.

The guide’s example (two executions of one plugin, different configuration, different phases) is the standard way to run a goal more than once with different settings:

This is the execution run in the lifecycle page (resources:3.5.0:copy-resources (copy-stations) in generate-resources).

Source: Maven guide: Using the executions tag

A plugin runs in its own class realm, with its own dependencies, apart from the project’s. Some plugins load extra classes at run time that you must supply: a different compiler for the compiler plugin, a different test provider for surefire, a JDBC driver for a SQL plugin, Ant tasks for the AntRun plugin. You add them with <dependencies> inside the <plugin>:

With the dependency, a one-class module compiles with the Eclipse compiler:

Without the <dependencies> block (same compilerId), the build fails with:

(The long first line was cut after the first sentence.) The plugin dependency’s version has to match what the plugin was built against. With plexus-compiler-eclipse:2.17.1 the same project failed against compiler plugin 3.16.0, which uses Plexus Compiler 2.17.0:

Look at the plugin’s POM (maven-compiler-plugin-3.16.0.pom defines plexusCompilerVersion as 2.17.0) when choosing such a version. Plugin dependencies are not project dependencies: they do not appear on the project’s classpath, and they are not inherited into the dependency graph of the artifact. The Ant counterpart of a plugin dependency is a library placed on the taskdef classpath; the Gradle counterpart is the buildscript classpath or pluginManagement.

Source: Maven guide: Using the dependencies tag

Source: Compiler plugin: Non-javac compilers

A child POM inherits the <build><plugins> of its parent, with the configuration and executions. To keep a plugin out of the children, set <inherited>false</inherited> on the plugin (or on a single execution). A parent that declares the Help plugin’s system goal in validate, once with the default and once with inherited false, in a two-module reactor (only the --- plugin --- lines shown):

<inherited> is a literal: an attempt to give it a property reference (${some.flag}) did not behave as a switch in the run (the goal ran only in the parent), so write true or false.

<build><pluginManagement> declares versions, configuration and executions for plugins without activating them: they take effect only for a plugin that is actually used, by the lifecycle (packaging bindings) or by a <plugin> entry in a <plugins> section. It is the plugin counterpart of dependencyManagement, and the place for plugin versions and shared configuration in a parent POM. The tidepool parent:

(groupId is omitted: it defaults to org.apache.maven.plugins.) maven-failsafe-plugin is managed here but is not used by tidepool-model, and the verify build of that module shows no failsafe line: management does not bind anything. The child modules do not repeat the versions, and every --- compiler:3.16.0:compile --- line in the logs on this page comes from this block. On Maven 3.10.0 the super POM no longer contains a pluginManagement section (it was removed in 3.10, together with the release-profile profile); on 3.9.x it managed only four plugins, maven-antrun-plugin, maven-assembly-plugin, maven-dependency-plugin and maven-release-plugin. The versions of the plugins bound by the packaging (clean, resources, compiler, surefire, jar, install and deploy, among others) never came from the super POM: they come from the lifecycle bindings of the running Maven, which still supply them on 3.10.0 but change from one Maven release to the next, so every project that wants stable versions must pin its own.

Source: Maven POM reference: Plugin Management

A plugin entry without a <version> is accepted, with a warning, and Maven decides the version: for a plugin bound by the packaging, the default that the running Maven carries; for another plugin, the latest release found in the repositories. Both change when Maven or the repository changes, so a build that worked last year can differ today. A minimal POM with a maven-jar-plugin declared without a version, run on the two Mavens:

(The blank [WARNING] lines were removed.) The same POM produced jars from two different plugin versions. Plugins also check the Maven version: a plugin line written for Maven 4 refuses to run on Maven 3. With maven-compiler-plugin 4.0.0-beta-5 (the Maven 4 line of the compiler plugin, a pre-release):

So the rule for this site is: pin every plugin in pluginManagement of the parent, stay on the 3.x lines of the plugins for Maven 3 (compiler 3.16.0, surefire 3.6.0, jar 3.5.1, and so on), and move to the 4.x lines only together with Maven 4.

A duplicate plugin entry is the other thing to clean up. A POM that declares maven-compiler-plugin twice in <plugins>:

This is one of the "stricter POM validation" changes of 3.10 (the escape hatch the release notes name is -Dmaven.resolver.validation=off; on 3.10.0 the lower-case value fails with No enum constant, and the property governs coordinate validation rather than this check, see Maven Dependencies, Scopes & Mediation). Use two <execution> elements instead of two <plugin> entries. The help plugin’s help:effective-pom shows the version Maven resolved for every plugin.

Source: Maven 3.10.0 release notes: Stricter POM validation

Source: Maven plugin compatibility plan

You type mvn jar:help, not mvn org.apache.maven.plugins:maven-jar-plugin:3.5.1:help. The short name, jar, is the plugin’s goal prefix. Maven turns a prefix into a groupId:artifactId as follows:

The metadata for a group is a plain XML file. This is the whole content for org.jacoco:

(From https://repo.maven.apache.org/maven2/org/jacoco/maven-metadata.xml; the org/apache/maven/plugins file lists 65 plugin entries at the time of writing.) Maven 3.10.0 also logs Loaded 24109 auto-discovered prefixes for remote repository central (prefixes-central.txt) at the start of each build; that is the repository’s published prefix list and is part of the remote repository filtering introduced in the 3.9 line, not a prefix mapping.

Source: Maven guide: Mapping Prefixes to Plugins

Running mvn jacoco:help in tidepool-model on Maven 3.10.0 first fails, because org.jacoco is not a default group (Maven 3.9.16 printed the same error). The two downloads are the two default groups:

The error message names the three places that were searched, which is exactly the lookup order above. There are three ways to fix it. The first is a settings.xml with the group added; run here with -s settings-groups.xml:

(Filtered.) The second is to declare the plugin in the POM (a project plugin is searched first), with a version, which also gives the plugin the pinned version it should have; with jacoco-maven-plugin 0.8.15 declared in a scratch POM, mvn jacoco:help printed --- jacoco:0.8.15:help (default-cli) --- with no pluginGroups at all. The third is to spell out the coordinates: mvn org.jacoco:jacoco-maven-plugin:0.8.15:help.

Source: Maven settings reference: Plugin Groups

The org.codehaus.mojo group is the default because of the MojoHaus plugins that moved out of Codehaus: mvn versions:help resolved versions-maven-plugin 2.23.0 from org.codehaus.mojo with no configuration, and, being unpinned, resolved to the latest release. Two further forms are accepted on the command line, both run here:

Both printed --- compiler:3.16.0:help (default-cli) ---. The prefix:version:goal form (version in the middle) is available since Maven 3.9.0 and is the way to run a goal at a specific version without a POM entry.

The prefix is chosen by the plugin author, conventionally the artifact id without the maven- and -plugin affixes (maven-jar-plugin is jar). Maven plugins named maven-*-plugin are reserved for the Apache Maven project; a third-party plugin is named <name>-maven-plugin so that its prefix is <name>, as with jacoco-maven-plugin and versions-maven-plugin.

Source: Maven guide: Configuring Maven to Search for Plugins

Source: Maven settings reference: Plugin Groups

Since Maven 3.9.0 and in Maven 4, Maven checks the plugins a build uses and reports configuration it knows is wrong or risky. The guide splits the problems into internal ones, which you fix in your POM (a deprecated parameter, a read-only parameter set in configuration, a deprecated goal), and external ones, which are defects of the plugin itself (it uses a deprecated Maven API, or declares Maven core artifacts in the wrong scope) and are fixed by upgrading or reporting them to the plugin authors.

A scratch POM, tidepool-validation-demo, makes three mistakes: it configures <sourceLevel> (a parameter the compiler plugin does not have), <systemProperties> (a deprecated surefire parameter) and <finalName> (a read-only parameter of the jar plugin). mvn -B package on 3.10.0:

The build succeeded, and the jar plugin even used the "read-only" name (renamed.jar). Validation does not stop the build; it warns that the next plugin release may. The behaviour is controlled by the user property maven.plugin.validation, whose values are case-insensitive NONE, INLINE (the default), BRIEF, SUMMARY and VERBOSE. It can be set on the command line, in MAVEN_OPTS or MAVEN_ARGS, in .mvn/maven.config, or as a settings.xml property, but not as a POM property. The same build with each value:

(Blank [WARNING] lines removed.) A plugin that you cannot fix can be excluded with -Dmaven.plugin.validation.excludes=<groupId>:<artifactId>:<version>[,...]. With the jar plugin excluded, the finalName warning disappeared and the other two kinds remained:

Maven 3.9.16 and 4.0.0-rc-7 printed the same four warnings for this project with the default setting. The old guide URL guide-plugin-validation.html under the mini guides is a 404; the page lives at guides/plugins/validation/.

Source: Maven guide: Plugin Validation

Source: Maven guide: Manage Plugin Validation verbosity

Source: Maven guide: Exclude plugins from validation

Reporting plugins are configured in <reporting><plugins>, optionally with <reportSets> to choose which of the plugin’s reports to generate and <inherited> as for build plugins. A scratch project with the Site plugin pinned in <build> and the Project Info Reports plugin in <reporting>:

mvn -B site produced target/site/summary.html and project-info.html and logged Configured 2 reports for maven-project-info-reports-plugin:3.9.0: summary, dependencies (the dependency report was skipped because the project had no dependencies). Configuration in <reporting> and in <build> do not have the same effect: since the Site plugin 3.4, mvn site uses the <configuration> of a plugin in <reporting> and, additionally, that of the same plugin in <build>; but a report goal invoked directly (mvn project-info-reports:summary) ignores <reporting> and uses only <build>.

Source: Maven guide: Using the reporting tag versus the build tag

Source: Maven guide: Using the reportSets tag

The Maven project’s plugin index lists the plugins it maintains, with their latest versions. The table gives the stable versions found on Maven Central on 2026-10-16 (the Maven 3 lines), by group, with their typical use. B means build plugin, R reporting plugin.

Source: Maven: Plugins supported by the Maven project

The index also lists the Maven 4 lines, which run only on Maven 4: maven-compiler-plugin 4.0.0-beta-5, maven-clean-plugin and maven-install-plugin and maven-deploy-plugin 4.0.0-beta-3, maven-resources-plugin 4.0.0-beta-2, all pre-releases at the time of writing; the run above shows the compiler plugin’s prerequisite check.

The migration view is in Migrating Between Tools and Migrating from Maven to Gradle.