Getting Started with Maven Wrapper
Maven-based projects require Apache Maven installed on the build systems. Traditionally, this was a manual step that users would do either by reading project documentation or the Maven reference manual.
Apache Maven Wrapper (formerly known as takari/maven-wrapper) simplifies this Maven installation process for building maven-based projects. This post will help you in getting started with Maven Wrapper.
1. Installing Maven Wrapper
The easiest way to install the Maven Wrapper for your existing projects is to use
This is one of the core plugins and thus does not require any modifications to project POM.
To install the maven wrapper, run the following command in the project base directory -
Running this command will add some new files in the base directory as below -
├── .mvn (1)
│ └── wrapper
│ ├── maven-wrapper.jar (2)
│ └── maven-wrapper.properties (3)
├── mvnw (4)
├── mvnw.cmd (5)
.mvn directory to hold wrapper related files
|A jar binary, used to bootstrap the download and invocation of Maven from the wrapper shell scripts
|Wrapper configuration properties
|Script to invoke maven commands on Linux/OSX/macOS/Solaris build systems
|Script to invoke maven commands on Windows build systems
Default wrapper configuration uses the maven version installed on the system where
wrapper:wrapper is invoked.
You can verify the version in
## Apache License Text removed for brevity
1.1 Using Different Initial Maven Version
When initializing the wrapper, you can specify the maven version to use.
The following command will generate a wrapper to use Maven 3.8.2, irrespective of the version on the init system.
mvn wrapper:wrapper -Dmaven=3.8.2
1.2 Upgrading Maven Version in Wrapper
To upgrade the maven version in the existing wrapper, you can use
-Dmaven=<version> argument and re-run the
Assuming that wrapper exists and uses Maven 3.8.2, running the following command in a base directory will modify the
maven-wrapper.properties file to use Maven 3.8.4.
mvn wrapper:wrapper -Dmaven=3.8.4
|Maven Wrapper should work with all 3.x Maven versions, but not with EOL’ed 2.x Maven versions.
1.3 Adding to Source Code Management
Once Maven Wrapper is generated, you should add newly generated files to the source code management (SCM) system along with your project source code. This ensures that everyone working on the project code gets the wrapper configuration.
If your SCM system does not allow adding binaries (eg. .jar files), you can exclude
from checkin/commit to SCM. For example, you would add that entry in .gitignore file for Git-based SCM systems. If the jar is not found locally, maven wrapper will download it.
2 Using Maven Wrapper
Now that the maven wrapper is configured in your project base directory,
mvnw.cmd should be used for running any maven commands.
./mvnw clean install
If the required Maven version isn’t available on the new build system, the wrapper will download it and use it for building the project.
You can run
--version to see the Maven version used by default
mvn installation (if any) on the build system
and the one used by the Maven Wrapper.
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /Users/manik/.sdkman/candidates/maven/3.6.3
Apache Maven 3.8.4 (9b656c72d54e5bacbed989b64718c159fe39b537)
Maven home: /Users/manik/.m2/wrapper/dists/apache-maven-3.8.4-bin/52ccbt68d252mdldqsfsn03jlf/apache-maven-3.8.4
Wrapper download binaries to a new
3. Environment Variables
Following are the environment variables that wrapper supports:
MVNW_VERBOSE: Default is
false. Setting it to
truewill make wrapper to output more information.
MVNW_USERNAME and MVNW_PASSWORD: Credentials to use when Maven Repository is password protected.
MVNW_REPOURL: To use internal Maven Repository Manager, you can either edit the maven-wrapper.properties file with internal URLs for binaries Or set this variable to the appropriate repository URL.
Maven Wrapper can simplify specifying maven version requirements and installation for maven-based projects. This post shows how to get started with the wrapper for your projects. You can read more about wrapper on Apache Maven Wrapper site.
Got a question? Comment on this article or find me on Twitter.
On this blog, I post articles about different technologies like Java, MuleSoft, and much more.
You can get updates for new Posts in your email by subscribing to JavaStreets feed here -