Getting Started with Maven Wrapper

December, 30 2021
Manik Magar
maven

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.

Table of Contents

1. Installing Maven Wrapper
2 Using Maven Wrapper
3. Environment Variables
4. Conclusion

1. Installing Maven Wrapper

The easiest way to install the Maven Wrapper for your existing projects is to use maven-wrapper-plugin. 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 -

mvn wrapper:wrapper

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)
├── pom.xml
└── src

1	`.mvn` directory to hold wrapper related files
2	A jar binary, used to bootstrap the download and invocation of Maven from the wrapper shell scripts
3	Wrapper configuration properties
4	Script to invoke maven commands on Linux/OSX/macOS/Solaris build systems
5	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 .mvn/maven-wrapper/maven-wrapper.properties.

maven-wrapper.properties

## Apache License Text removed for brevity

distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.8.1/apache-maven-3.8.1-bin.zip
wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.1.0/maven-wrapper-3.1.0.jar

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 wrapper:warpper goal.

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 .mvn/wrapper/maven-wrapper.jar file 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 or 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.

Default Maven on the system

mvn --version
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /Users/manik/.sdkman/candidates/maven/3.6.3

Maven Version used by Wrapper

./mvnw --version
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 ~/.m2/wrapper/dists/ directory.

3. Environment Variables

Following are the environment variables that wrapper supports:

MVNW_VERBOSE: Default is false. Setting it to true will 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.

4. Conclusion

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.

Follow @manikmagar on twitter to get updates on new posts.