Developer Productivity Engineering Blog
Build Best Practices

Use the Maven Wrapper to optimize your build workflow

By Brian Demers
October 7, 2024

If you’re a Java developer, chances are Apache Maven™ is a core part of your toolkit. But let’s face it, managing Maven versions across different environments—your local machine, your team’s setups, and your CI/CD pipelines—can be a real pain. Inconsistent installations, manual updates, and the dreaded “it works on my machine” syndrome can all slow you down and cause unnecessary headaches.

Enter the Maven Wrapper—a simple tool that transparently manages your Maven installation for you!

A brief history of the Maven Wrapper

The Maven Wrapper started as a solution to the problem of inconsistent build environments—much like the Gradle Wrapper. I took the idea and adapted the Gradle Wrapper code to create the first working version for Maven. Later, Takari adopted the project and improved and maintained it. More recently, it became part of the Apache Maven project—which was the goal all along—and it continues to improve with features like a “script-only” mode and integration with tools like Maven Daemon.

Why every Maven project needs a wrapper

  1. One version of Maven everywhere: The wrapper ensures that the exact same Maven version is used everywhere your project is built. Does your CI system use a different version of Maven than you do? The wrapper fixes that—no more surprises when a build works perfectly on your machine but fails on the CI server. It’s consistency you can count on.
  2. Reproducible builds: By locking down the Maven version, the wrapper plays a crucial role in ensuring that your builds are reproducible. This means fewer variables that could cause builds to fail or behave differently across environments.
  3. Easier onboarding for new developers: The wrapper simplifies the setup process for new developers. With the wrapper in place, new team members can get up and running with the correct Maven version immediately, leading to quicker onboarding and fewer setup-related issues.
  4. Upgrading made easy: Forget about manually downloading and installing new Maven versions. With the wrapper, upgrading is as easy as changing a single line in a configuration file. The wrapper takes care of the rest, automatically downloading and applying the new version.
  5. Lean and mean: The recent “only script” mode eliminates the need for a binary JAR file, making your project more streamlined and adhering to the “no binaries” policies that many teams prefer.

How to make the Maven Wrapper your new best friend

Ready to give the Maven Wrapper a try? It’s surprisingly easy to get started:

  1. Maven Wrapper Plugin: There is a plugin for Maven that can configure and update your project to use the Maven Wrapper. From your project’s root directory, run:

mvn wrapper:wrapper

This will set up the wrapper scripts (mvnw and mvnw.cmd) and the configuration file with the current version of Maven you are using.

NOTE: As of 3.2.0, the “only-script” option is the default type; if you used a previous version, you may need to add the -Dtype=only-script parameter to the above command.

  1.  Swap ‘mvn’ for ‘mvnw’: From now on, instead of typing mvn, use mvnw (or mvnw.cmd on Windows) for all your Maven commands:

./mvnw clean verify

  1. Upgrade at will: To change the Maven version, just edit the distributionUrl property in the .mvn/wrapper/maven-wrapper.properties file. Or run mvn wrapper:wrapper -Dmaven=<new-version>. The next time you run mvnw, the wrapper will automatically download and use the new version.
  2. Maven mirror support: If you’re using a corporate Maven artifact repository like Nexus or Artifactory, the mirror URL will be used automatically.

Going the extra mile with mvnd

For those who crave the fastest possible builds, the Maven Wrapper also integrates with mvnd, the high-performance Maven Daemon. While you don’t strictly need the wrapper to use mvnd, the integration makes setup a breeze. Just add one more property to enable it:

mvn wrapper:wrapper -Dmvnd=<mvnd_version>

To use Maven wrapper 1.0.2 with mvnd:

mvn wrapper -Dmvnd=1.0.2

Add the Maven Wrapper to source control

After adding the Maven Wrapper to your project, commit the wrapper scripts (mvnw and mvnw.cmd) and the .mvn directory to source control. This ensures that everyone on your team is on the same page when building the project. The .mvn/wrapper/maven-wrapper.properties file offers a few additional settings you can tweak to customize the wrapper’s behavior. You can learn more about these settings, as well as more advanced use cases, in the official Maven Wrapper documentation.

Wrap it up!

The Maven Wrapper is a small but mighty tool that can significantly improve your Maven workflow. It guarantees consistent builds, simplifies setup for new developers, ensures reproducibility, makes upgrades a breeze, and even gives you a speed boost if you use mvnd. Why not give it a shot? You might just wonder how you ever lived without it!

Interested in learning more about best practices and speeding up your Maven builds? Check out these posts:

For more great content, follow us on Twitter and LinkedIn or subscribe to our YouTube channel.