Maven Wrapper Installation

06.06.2024 — maven — 4 min read

Overview

Maven is a beautiful tool for Java projects management and builds automation. However you need it installed locally before you can start with the project.

Maven Wrapper is a solution to get rid of ~~installed locally~~ requirement, making your project more portable and convenient for developers, contributors and CI/CD integrations.

There are several ways to install it in your project:

copy-paste from another project;
extract from binaries distribution;
use wrapper:wrapper` plugin.

Installation by Copy-Paste

This is the simplest and the most convenient way to install Maven Wrapper.

Prerequisites:

JVM installed and java available on PATH
~~No need for local Maven~~

At first, choose any existing project already using Maven Wrapper (for example netty.io). Then copy-paste the following files into the root folder of your project:

1$ find . -type f | sort -r
2./mvnw.cmd
3./mvnw
4./.mvn/wrapper/maven-wrapper.properties
5./.mvn/wrapper/maven-wrapper.jar

Restore executable flag for mvnw if necessary:

1$ chmod +x mvnw

Check it works:

1$ ./mvnw --version
2Apache Maven 3.9.7 (8b094c9513efc1b9ce2d952b3b9c8eaedaf8cbf0)
3Maven home: ...
4Java version: ...

Done!

Installation From Distribution

This way is also very simple, but requires more steps, compared to copy-paste approach.

Prerequisites:

JVM installed and java available on PATH
~~No need for local Maven~~

Maven Wrapper binaries are distributed via Maven Public Repository.

Choose version you want to work with (e.g. 3.3.2) and open View All files. Get the direct link to maven-wrapper-distribution-<version>-bin.zip file.

1$ curl https://repo1.maven.org/maven2/org/apache/maven/wrapper/maven-wrapper-distribution/3.3.2/maven-wrapper-distribution-3.3.2-bin.zip -o maven-wrapper-distribution.zip
2...
3
4$ unzip maven-wrapper-distribution.zip -x mvnwDebug\*
5...
6
7$ find . -type f | sort -r
8./mvnw.cmd
9./mvnw
10./.mvn/wrapper/maven-wrapper.jar

Note! File .mvn/wrapper/maven-wrapper.properties is missing. You need to create it explicitly:

1$ echo 'distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.7/apache-maven-3.9.7-bin.zip' > .mvn/wrapper/maven-wrapper.properties
2
3$ cat .mvn/wrapper/maven-wrapper.properties
4distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.7/apache-maven-3.9.7-bin.zip

Check it works:

1$ ./mvnw --version
2Apache Maven 3.9.7 (8b094c9513efc1b9ce2d952b3b9c8eaedaf8cbf0)
3Maven home: ...
4Java version: ...

Done!

Installation by Plugin

Follow this way if you already have Maven installed locally. This approach is an official one and is described on the main page of the Maven Wrapper.

Prerequisites:

JVM installed and java available on PATH
Maven installed and mvn available on PATH

Choose version of Maven you want to work with, e.g. 3.8.4:

1$ mvn wrapper:wrapper -Dtype=bin -Dmaven=3.8.4
2...
3
4$ find . -type f | sort -r
5./mvnw.cmd
6./mvnw
7./.mvn/wrapper/maven-wrapper.properties
8./.mvn/wrapper/maven-wrapper.jar

Check it works:

1$ ./mvnw --version
2Apache Maven 3.9.7 (8b094c9513efc1b9ce2d952b3b9c8eaedaf8cbf0)
3Maven home: ...
4Java version: ...

Done!

Installation via wrapper:wrapper plugin has a lot of configurable options. To get them all use the following command:

1$ mvn wrapper:help -Dgoal=wrapper -Ddetail=true
2...
3wrapper:wrapper
4  Unpacks the maven-wrapper distribution files to the current project source
5  tree.
6
7  Available parameters:
8
9    alwaysDownload (Default: false)
10      Determines if the Maven distribution should be downloaded on every
11      execution of the Maven wrapper.
12      User property: alwaysDownload
13
14    alwaysUnpack (Default: false)
15      Determines if the Maven distribution should be unpacked on every execution
16      of the Maven wrapper.
17      User property: alwaysUnpack
18
19    distributionSha256Sum
20      The expected SHA-256 checksum of the Maven distribution that is executed
21      by the installed wrapper.
22      User property: distributionSha256Sum
23
24    distributionType
25      The Maven Wrapper distribution type.
26      Options are:
27      script
28          only mvnw scripts
29      bin
30          precompiled and packaged code
31      source
32          Java source code, will be compiled on the fly
33      only-script (default)
34          the new lite implementation of mvnw/mvnw.cmd scripts downloads the maven
35          directly and skips maven-wrapper.jar - since 3.2.0
36          If -Dtype={type} is not explicitly provided, then distributionType from
37          .mvn/wrapper/maven-wrapper.properties is used, if it exists. Otherwise,
38          only-script is used as the default distribution type.
39          This value will be used as the classifier of the downloaded file.
40      User property: type
41
42    includeDebugScript (Default: false)
43      Include mvnwDebug* scripts?
44      User property: includeDebug
45
46    mavenVersion
47      The version of Maven to require, default value is the Runtime version of
48      Maven. Can be any valid release above 2.0.9
49      User property: maven
50
51    mvndVersion
52      The version of Maven Daemon to require.
53      User property: mvnd
54
55    wrapperSha256Sum
56      The expected SHA-256 checksum of the maven-wrapper.jar that is used to
57      load the configured Maven distribution.
58      User property: wrapperSha256Sum

Important Notes

Since version 3.2.0 Maven Wrapper uses only-script distribution type. This setup would work for a wast majority of open-source projects.

However in commercial development (behind corporate proxies, using private repositories or legacy OS's) this would NOT work. Thus it's better to enforce bin distribution type as shown in examples above.

Also, you can configure Maven Wrapper to use any Maven distribution, e.g. from your private repository:

1$ cat .mvn/wrapper/maven-wrapper.properties
2distributionUrl=https://<private repository>/<path>/mvn-3.8.4-patched.zip

Conclusion

In this guide you've learned how to install Maven Wrapper for your Java project.

This tool will give you a convenient and portable way to manage your builds:

1$ ./mvnw clean install