Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 41 ยท Getting Started

Installing Maven and the Wrapper

Install a JDK and Apache Maven on Windows, macOS or Linux, set JAVA_HOME, check mvn -v, and use the Maven Wrapper so every machine builds with the same version.

Maven is a Java program, so it needs a JDK (Java Development Kit) on your machine, not just a JRE. A JDK contains the compiler javac, which Maven calls to compile your code. After the JDK you install Maven itself, which is just an archive you unpack and put on your PATH.

There is a second route that avoids installing Maven globally at all: the Maven Wrapper. It is a small script checked into your project that downloads the right Maven version on first use. Most professional projects use it, so this lesson covers both.

Everything in this lesson is a command you run in your own terminal, so the code blocks are read-only. The runnable examples at the end are stand-ins that parse the same text Maven and the wrapper produce.

What you need

A JDK Provides javac. A JRE is not enough.
Maven Unpack it and add bin to PATH.
mvn -v Shows Maven, Java and OS versions.
1 / 2

Step 1: install a JDK

Pick a current long-term-support JDK, such as Java 21 or Java 25, from any vendor you trust (Eclipse Temurin, Oracle, Amazon Corretto, Microsoft and others all work). Maven does not care which vendor you choose.

  • Windows: run the installer, or use a package manager such as winget.
  • macOS: use the installer, or Homebrew.
  • Linux: use your distribution's package manager, or a tool like SDKMAN!.

Check that the compiler is available:

TEXT
java -version
javac -version

If javac is "not found" but java works, you only have a JRE. Install a full JDK.

Step 2: set JAVA_HOME

Maven finds Java through the JAVA_HOME environment variable (and falls back to the java on your PATH). Set JAVA_HOME to the folder that contains the JDK's bin directory, not to the bin folder itself.

Terminal
# Linux or macOS: add to ~/.bashrc or ~/.zshrc
export JAVA_HOME="/usr/lib/jvm/temurin-25-jdk"
export PATH="$JAVA_HOME/bin:$PATH"
TEXT
:: Windows (Command Prompt), or use the System Properties dialog
setx JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-25"

Open a new terminal afterwards, because running shells do not see the change. The exact folder name depends on your JDK and version; look at your install location.

A very common mistake is setting JAVA_HOME to .../jdk-25/bin. That produces the error "The JAVA_HOME environment variable is not defined correctly". Point it at the parent folder.

Step 3: install Maven

You have two easy options.

  1. Package manager. On macOS, Homebrew installs it. On Linux, apt, dnf or SDKMAN! work, though distribution packages can lag behind. On Windows, winget or Chocolatey are available.
  2. Manual install. Download the binary archive (apache-maven-<version>-bin.zip or .tar.gz) from the official Apache Maven site, unpack it somewhere permanent, and add its bin folder to PATH.

Then verify:

TEXT
mvn -v

A typical result looks like this (your numbers will differ):

TEXT
Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /opt/apache-maven-3.9.9
Java version: 25, vendor: Eclipse Adoptium, runtime: /usr/lib/jvm/temurin-25-jdk
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "6.8.0", arch: "amd64", family: "unix"

Read it from top to bottom. Line one is the Maven version. "Maven home" shows where Maven is installed. The Java line is the JDK Maven will use for builds, which is the most common thing to check when something fails. If it shows a Java version you did not expect, fix JAVA_HOME.

Maven 3.9 or Maven 4?

Two lines of Maven exist. Maven 3.9.x is the long-established, widely deployed line, and it needs at least Java 8 to run. Maven 4 is the next generation: it keeps most of the Maven 3 behavior but adds features such as a newer POM model, improved multi-module support and better build performance. It requires a newer Java (17 or above) to run Maven itself.

For learning, either works, and everything in this tutorial applies to both unless a lesson says otherwise. If your team has a standard, follow it; the wrapper (below) is how teams pin that choice. Check the release notes on the Apache Maven site for the current status.

The Java that runs Maven and the Java version your code is compiled for are separate things. A JDK 25 can compile code for Java 17 using maven.compiler.release. You will set that in Properties and Build Settings.

The Maven Wrapper

The wrapper solves a team problem: "it builds on my machine, but I have Maven 3.6 and you have 3.9." Instead of asking everyone to install the same version, you add a script to the project that fetches the version the project wants.

Generate it once, from a project that already has a pom.xml, using a machine that has Maven installed:

TEXT
mvn wrapper:wrapper
mvn wrapper:wrapper -Dmaven=3.9.9

The second form pins an exact Maven version. The command adds these files, which you commit to version control:

TEXT
my-project/
โ”œโ”€โ”€ mvnw                     (script for Linux and macOS)
โ”œโ”€โ”€ mvnw.cmd                 (script for Windows)
โ”œโ”€โ”€ pom.xml
โ””โ”€โ”€ .mvn/
    โ””โ”€โ”€ wrapper/
        โ””โ”€โ”€ maven-wrapper.properties

The interesting file is maven-wrapper.properties:

TEXT
wrapperVersion=3.3.2
distributionType=only-script
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip

The key line is distributionUrl: it names the Maven distribution to download. From now on, anyone builds with:

TEXT
./mvnw package        (Linux and macOS)
mvnw.cmd package      (Windows)

The first run downloads that Maven into your home directory (under ~/.m2/wrapper), and later runs reuse it. Teammates and CI servers need only a JDK. To upgrade Maven for everybody, change the URL (or re-run wrapper:wrapper -Dmaven=...) and commit the change.

Besides the wrapper, the .mvn folder can hold other project-wide settings: jvm.config (JVM options for Maven itself), maven.config (default command-line flags) and extensions.xml. They live with the project, so every developer gets them automatically.

flowchart LR
    A["./mvnw package"] --> B{"Maven version<br/>in ~/.m2/wrapper?"}
    B -- yes --> D["run mvn package"]
    B -- no --> C["download distributionUrl"]
    C --> D

The wrapper downloads Maven once, then behaves exactly like mvn.

Stand-in: reading the tool output

The real commands cannot run here, but the text they print is plain, and parsing it is a good way to see what each line means. The first model reads a mvn -v output and checks whether the Java version can run Maven 3.9 and Maven 4. The minimum versions are taken from the section above.

Java Check Java against Maven's needs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The model only reads two lines. The real mvn -v also reports the locale and OS, and old Java versions print 1.8.0_xxx instead of 8, which this simple parser does not handle.

The second model reads maven-wrapper.properties and works out which Maven the wrapper would download and where it would be unpacked, which is the heart of what mvnw does.

Java What will mvnw download?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The real wrapper adds a hash of the URL to the folder name, so two different download URLs never share a cache entry. The model shows <hash> instead of computing it.

Which command should you use?

Once a project has a wrapper, prefer ./mvnw over mvn. It guarantees the version, and CI and teammates behave identically. On a project without one, mvn is fine. The rest of this tutorial writes mvn for brevity; substitute ./mvnw whenever your project has a wrapper.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does Maven need a JDK rather than only a JRE?

    Compiling your sources needs javac, which ships with the JDK. A JRE can run programs but cannot compile them.
  2. 2. What should JAVA_HOME point to?

    JAVA_HOME is the JDK's root folder (the parent of bin). Pointing it at bin itself causes the "not defined correctly" error.
  3. 3. What does the Maven Wrapper give a team?

    mvnw reads the distributionUrl in maven-wrapper.properties and downloads that Maven, so everyone and CI use the same version.
  4. 4. Which line of mvn -v tells you the Java that Maven will use for builds?

    The "Java version" line shows the JDK Maven runs on. If it is not what you expect, check JAVA_HOME.

Summary

  • Install a full JDK first; set JAVA_HOME to its root folder; open a new terminal.
  • Install Maven from a package manager or by unpacking the binary archive and adding bin to PATH.
  • mvn -v shows the Maven version, the Java it runs on and the OS; check it whenever a build behaves oddly.
  • Maven 3.9 is the widely deployed line; Maven 4 adds new features and needs a newer Java to run.
  • The wrapper (mvnw, mvnw.cmd, .mvn/wrapper/) pins Maven per project, so teammates and CI need only a JDK.

Now build something: Your First Maven Project.