/flags/maven/mvn-pl-am-build-selected-modules
mvn -pl module -am: build only selected modules of a multi-module project
- tool
- Maven
- command
- mvn
- flag
- -pl, --projects LIST; -am, --also-make; -amd, --also-make-dependents
- default
- all modules of the reactor are built
In a multi-module Maven project, mvn install builds every module listed in the parent POM. mvn install -pl api -am (long forms --projects and --also-make) builds only the api module plus the modules it depends on, in the right order. -pl alone builds just the listed modules and expects their sibling dependencies to be in the local repository already; -amd adds the modules that depend on the selection instead. This is the standard way to speed up local builds and CI jobs in large reactors.
Example layout
shop/
├── pom.xml (packaging pom, modules: core, api, web, docs)
├── core/ (no internal dependencies)
├── api/ (depends on core)
├── web/ (depends on api)
└── docs/mvn install -pl api # builds api only; core must already be installed
mvn install -pl api -am # builds core, then api
mvn install -pl api -amd # builds api, then web
mvn install -pl api -am -amd # core, api, web
mvn install -pl '!docs' # everything except docsMaven prints the selected modules in the "Reactor Build Order" at the start and in the "Reactor Summary" at the end, so you can check which modules were built.
How modules are named
| Form | Example |
|---|---|
| Relative path of the module directory | -pl api or -pl services/api |
| artifactId with a leading colon | -pl :shop-api |
| groupId:artifactId | -pl com.example:shop-api |
| Several modules, comma-separated | -pl core,api |
| Exclusion with ! or - | -pl '!docs' or -pl -docs |
A name that matches no module stops the build with Could not find the selected project in the reactor. Check the spelling against the <module> entries or the artifactId.
Related reactor options
| Option | Effect |
|---|---|
| -am, --also-make | Also build the dependencies of the selected modules |
| -amd, --also-make-dependents | Also build the modules that depend on them |
| -rf, --resume-from MODULE | Resume a failed build from this module |
| -T 4 | Build independent modules in parallel |
| -f path/pom.xml | Use another POM as the reactor root |
After a failure Maven itself suggests the -rf :module command line to resume from the module that failed, so modules that already succeeded are not rebuilt.
Pitfalls
- Run the command from the parent directory (or point at it with
-f); inside a module directory the reactor contains only that module. Running Maven where there is no POM at all fails with there is no POM in this directory. -plwithout-amplusmvn package(notinstall) is a common trap: sibling modules are never installed, so the next selective build cannot resolve them.- Plugins that aggregate over all modules (coverage reports, javadoc aggregates) see only the selected subset.
- Running a single test in one module combines both ideas:
mvn test -pl api -am -Dtest=OrderTest -Dsurefire.failIfNoSpecifiedTests=false, see run a single test with Maven. - Parallel builds with mvn -T work well together with
-pl, because Maven still respects module order.
FAQ
What is the difference between -am and -amd?
-am (--also-make) adds the modules that the selected modules depend on, so they are built first. -amd (--also-make-dependents) adds the modules that depend on the selected ones, which is what you want to check that a change in a library does not break its users.
How do I exclude one module from the build?
Prefix it with ! or - in the list: mvn install -pl '!docs' builds everything except the docs module. Quote the argument in bash and zsh, where ! has a special meaning.
Why does mvn -pl fail to find artifacts of other modules?
Without -am, Maven builds only the listed modules and takes their sibling dependencies from the local repository. If those were never installed (mvn install), resolution fails. Add -am or install the whole project once.