Maven Wrapper

The Maven Wrapper is an easy way to ensure a user of your Maven build has everything necessary to run your Maven build.

Why might this be necessary? Maven to date has been very stable for users, is available on most systems or is easy to procure: but with many of the recent changes in Maven it will be easier for users to have a fully encapsulated build setup provided by the project. With the Maven Wrapper, this is very easy to do and it's a great idea and initial implementation borrowed from Gradle.

The easiest way to setup the Maven Wrapper for your project is to use the Maven Wrapper Plugin with its provided wrapper goal. To add or update all the necessary Maven Wrapper files to your project execute the following command:

mvn wrapper:wrapper
Normally you instruct users to install a specific version of Apache Maven, put
it on the PATH and then run the mvn command like the following:
mvn clean install
But now, with a Maven Wrapper setup, you can instruct users to run wrapper
scripts:
./mvnw clean install
or on Windows
mvnw.cmd clean install
A normal Maven build will be executed, with the one important change that if the
user doesn't have the necessary version of Maven specified in
.mvn/wrapper/maven-wrapper.properties it will be downloaded for the user
first, installed and then used.
Subsequent uses of mvnw/mvnw.cmd use the previously downloaded, specific
version as needed.

Supported Systems

The wrapper should work on various operating systems including
Linux (numerous versions, tested on Ubuntu and CentOS)
OSX / macOS
Windows (various newer versions)
Solaris (10 and 11)
A POSIX-compatible Bourne shell is required to run the wrapper script.
In terms of Apache Maven versions itself, the wrapper should work with any Maven
3.x version and it defaults to the release used when setting up the wrapper. We do NOT
plan to support the deprecated, EOL'ed Maven 2.x.
By default, the only-script type is installed (see below).

Verbose Mode

The wrapper supports a verbose mode in which it outputs further information. It
is activated by setting the MVNW_VERBOSE environment variable to true.
By default it is off.

Usage with or without Binary JAR

Using type=bin, the Maven Wrapper JAR archive is added to the using project as small
binary file .mvn/wrapper/maven-wrapper.jar. It is used to bootstrap the
download and invocation of Maven from the wrapper shell scripts.
If your project is not allowed to contain binary files like this, you can
use the source distribution of the maven wrapper which adds a file
.mvn/wrapper/MavenWrapperDownloader.java file instead:
mvn wrapper:wrapper -Dtype=source 
You can also choose to opt out of all additional resources except the wrapper scripts:
mvn wrapper:wrapper -Dtype=script
Another type is the lite implementation of mvnw/mvnw.cmd scripts which download the maven directly
via wget or curl on *nix, or PowerShell on Windows, then call the original mvn/mvn.cmd
scripts of the downloaded maven distribution.
This type does not use maven-wrapper.jar nor MavenWrapperDownloader.java, only the wrapper scripts are required.
This is the default type being installed, when no type parameter is specified.
mvn wrapper:wrapper -Dtype=only-script
If the JAR is not found to be available by the scripts they will attempt to
download the file from the URL specified in
.mvn/wrapper/maven-wrapper.properties under wrapperUrl and put it in place.
The download is attempted via curl, wget and, as last resort, by compiling the
.mvn/wrapper/MavenWrapperDownloader.java file and executing the resulting
class.
If your Maven repository is password protected you can specify your username via
the environment variable MVNW_USERNAME and the password via the environment
variable MVNW_PASSWORD.

Using a Different Version of Maven

To switch the version of Maven used to build a project, you can initialize it
using:
mvn wrapper:wrapper -Dmaven=3.5.4
which works for any version except snapshots. Once you have a wrapper you can
change its version by setting the distributionUrl in
.mvn/wrapper/maven-wrapper.properties, e.g.
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.5.4/apache-maven-3.5.4-bin.zip
Using Basic Authentication for Distribution Download

To download Maven from a location that requires Basic Authentication you have 2
options:
add user and password to the distributionUrl like that:
distributionUrl=https://username:password@<yourserver>/maven2/org/apache/maven/apache-maven/3.2.1/apache-maven-3.2.1-bin.zip
Specifying Maven Distribution Base Path

This is a feature of Maven itself and the wrapper just happens to take it into
account. Simply set MAVEN_USER_HOME to the desired path and the wrapper uses
it as the base of the Maven distro installation.
See https://www.lewuathe.com/maven-wrapper-home.html and
https://github.com/takari/maven-wrapper/issues/17

Using a Maven Repository Manager

When using an internal Maven repository manager, you have two options:
Just set the correct URL to wrapper jar and Maven distro in
maven-wrapper.properties in your project
Leave the default URL in the project pointing to Maven Central and set the
environment variable MVNW_REPOURL to your repo manager URL such as
https://repo.example.com/central-repo-proxy.
If MVNW_REPOURL is set during the wrapper installation with the
maven-wrapper-plugin, the URL is used in the maven-wrapper.properties file.
If not set, but your mirror URL in your settings.xml is configured, it will be
used.

Checksum verification of downloaded binaries

To avoid supply-chain-attacks by downloading a corrupted artifact, it
is possible to specify checksums for both the maven-wrapper.jar and
the downloaded distribution. To apply verification, add the expected
file's SHA-256 sum in hex notation, using only small caps, to
maven-wrapper.properties. The property for validating the
maven-wrapper.jar file is named wrapperSha256Sum whereas the
distribution file property is named distributionSha256Sum.

Internals

Maven Wrapper is composed of 3 pieces: