How to Install Maven on Windows, Linux and macOS

A classic post-install surprise: Maven is unpacked, PATH is set, and yet mvn -version replies with The JAVA_HOME environment variable is not defined correctly, this environment variable is needed to run this program. The variable is defined - as C:\Program Files\Java\jdk-21\bin. Maven appends \bin\java.exe to it, looks for ...\bin\bin\java.exe and finds nothing. This guide walks through the installation so that errors like this never show up.

Installing Maven means downloading the Apache Maven distribution (an archive of ready-to-run files), unpacking it and adding its bin directory to the PATH environment variable so that the mvn command works from any folder. Maven also needs an installed JDK. There is no classic installer: on Windows, installation comes down to unpacking the archive and setting environment variables, while on Linux and macOS a package manager (apt, dnf, brew) or SDKMAN is usually more convenient.

Prerequisites: What You Need Before Installing Maven

Before installing Maven you need a JDK (not just a JRE): Maven 3.10.0 (the recommended version) and the previous 3.9.x line run on Java 8 or newer, while Maven 4 (still in preview) requires Java 17 or newer. Maven finds Java through the JAVA_HOME variable (the JDK root) or, if it is not set, through the java command on the PATH. A manual installation does not require administrator rights.

Check that a JDK is already installed and visible in the terminal:

java -version
javac -version

If javac is not found, you either have only a JRE or the JDK is not on the PATH - install a JDK first (for example, Eclipse Temurin or Oracle JDK). A Maven build on a JRE alone fails at the compile step; see common installation errors.

If you only work in IntelliJ IDEA or Eclipse, Maven is already bundled with the IDE. A separate installation is needed to run mvn in a terminal, in scripts and on a CI server.

Ways to Install Maven: Which One to Choose

You can install Maven manually from the official archive (works on any OS and gives you the latest version), through your system's package manager (faster, but the version is sometimes older) or with SDKMAN (handy for keeping several versions). For a single project you may not need a global installation at all if the project ships with the Maven Wrapper.

Where to Download Maven and Which File to Pick

Download Maven from the official Apache site: on maven.apache.org/download.cgi, in the "Files" section, choose the Binary zip archive (apache-maven-3.10.0-bin.zip) for Windows or the Binary tar.gz archive (apache-maven-3.10.0-bin.tar.gz) for Linux and macOS. Archives with src in the name contain source code and are not meant for installation.

Both binary archives contain exactly the same files: Maven is written in Java and does not depend on the OS, only the packaging format differs. This is also the "portable" Maven: you can copy the unpacked folder to a USB stick or another directory, and bin\mvn -version runs from there without any installation.

The examples in this lesson use version 3.10.0 - substitute the current stable release number from the download page. To download the archive from a terminal:

# Linux / macOS
wget https://dlcdn.apache.org/maven/maven-3/3.10.0/binaries/apache-maven-3.10.0-bin.tar.gz

# Windows (PowerShell)
Invoke-WebRequest https://dlcdn.apache.org/maven/maven-3/3.10.0/binaries/apache-maven-3.10.0-bin.zip -OutFile apache-maven-3.10.0-bin.zip

The dlcdn.apache.org mirror keeps only current versions. If the link returns 404, a newer version has been released, and older ones are available in the archive at https://archive.apache.org/dist/maven/maven-3/.

Verify the checksum. Next to each archive on the download page there is a link to a .sha512 file. Compute the hash of the downloaded file and compare it with the contents of the .sha512 file - the strings must match exactly:

# Windows (PowerShell)
Get-FileHash .\apache-maven-3.10.0-bin.zip -Algorithm SHA512

# Linux
sha512sum apache-maven-3.10.0-bin.tar.gz

# macOS
shasum -a 512 apache-maven-3.10.0-bin.tar.gz

PowerShell prints the hash in uppercase, while the .sha512 file uses lowercase - that is fine, the comparison is case-insensitive.

How to Install Maven on Windows 10 and 11

To install Maven on Windows, unzip the archive into a folder without spaces (for example, C:\dev), set the JAVA_HOME variable to the JDK root and add C:\dev\apache-maven-3.10.0\bin to the Path variable. Then open a new terminal window and run mvn -version. The steps are the same on Windows 10 and Windows 11.

Step 1. Unzip the archive

Use File Explorer (right-click → "Extract All") or PowerShell:

Expand-Archive .\apache-maven-3.10.0-bin.zip -DestinationPath C:\dev

You get the folder C:\dev\apache-maven-3.10.0 with the subfolders bin, boot, conf and lib. Make sure you did not end up with a nested apache-maven-3.10.0\apache-maven-3.10.0\bin - in that case Path must point to the inner bin. C:\Program Files also works, but writing to it requires administrator rights, and a path without spaces avoids trouble with older scripts.

Step 2. Open the Environment Variables dialog

Press Win+R, type sysdm.cpl → the "Advanced" tab → the "Environment Variables" button. Alternatively, type "Edit the system environment variables" into Windows search. Variables in the upper block ("User variables") apply only to your account and need no administrator rights; the lower block ("System variables") applies to all users.

Step 3. Set JAVA_HOME

Click "New", enter the name JAVA_HOME and the JDK root as the value, for example C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot. No \bin at the end: this folder must contain a bin subfolder with java.exe and javac.exe. If the JDK installer already created JAVA_HOME, check its value.

Step 4. Add Maven to Path

Select the Path variable → "Edit" → "New" and enter C:\dev\apache-maven-3.10.0\bin. Optionally, create MAVEN_HOME = C:\dev\apache-maven-3.10.0 first and add %MAVEN_HOME%\bin to Path - then upgrading Maven means changing a single value. Maven itself does not require MAVEN_HOME, and M2_HOME from older tutorials has been ignored since Maven 3.5.0, so you can skip it.

Step 5. Check in a new terminal

Close every open cmd, PowerShell and IDE terminal: processes that are already running do not see new variables. Open a new window and run mvn -version - the expected output is shown in Verify the Installation.

The same result from PowerShell, without the GUI (user variables, no administrator rights needed):

[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot", "User")
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;C:\dev\apache-maven-3.10.0\bin", "User")

Installing Maven with a Windows package manager

Package managers download Maven and add it to Path for you; the JDK must be installed beforehand.

# Chocolatey (run the console as administrator)
choco install maven

# Scoop (no administrator rights)
scoop install maven

# winget: find the package ID first
winget search maven

The winget catalog is maintained by the community, so before running winget install check with winget search whether Maven is available and what its exact ID is.

How to Install Maven on Linux

On Linux, Maven is installed with a single package manager command: sudo apt install maven on Debian and Ubuntu, sudo dnf install maven on Fedora, apk add maven on Alpine. If you need the latest version, unpack the archive from maven.apache.org into /opt and add bin to PATH in ~/.bashrc.

Using a package manager

# Debian, Ubuntu, Linux Mint
sudo apt update
sudo apt install maven

# Fedora, RHEL, Rocky Linux
sudo dnf install maven

# Alpine (the subcommand is "add", not "install")
apk add maven

# Arch Linux
sudo pacman -S maven

Repository versions usually lag behind: Ubuntu 22.04 installs Maven 3.6.3, Ubuntu 24.04 and Debian 12 install 3.8.7. That is enough for learning projects, but recent plugin versions sometimes require a newer Maven. The package may also pull in OpenJDK as a dependency - the JDK Maven actually uses is shown in the mvn -version output.

Manually from the archive

sudo tar -xzf apache-maven-3.10.0-bin.tar.gz -C /opt
sudo ln -s /opt/apache-maven-3.10.0 /opt/maven

# append to ~/.bashrc (or ~/.zshrc)
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH=/opt/maven/bin:$PATH

To apply the changes in the current terminal, run source ~/.bashrc. The /opt/maven symlink makes upgrades easy: unpack the new version next to the old one and repoint the link with sudo ln -sfn /opt/apache-maven-3.10.1 /opt/maven - no need to edit ~/.bashrc. To find the JDK path, run readlink -f $(which java) and drop the trailing /bin/java. If Maven is installed both from a package and manually, whichever directory comes first in PATH wins - check with which mvn.

How to Install Maven on macOS

On macOS the easiest way to install Maven is Homebrew: brew install maven, and brew upgrade maven to update it. A manual installation works the same way as on Linux: unpack the tar.gz archive and add bin to PATH in ~/.zshrc (zsh is the default shell on macOS).

brew install maven
mvn -version

Installing Maven with SDKMAN

SDKMAN is a version manager for Java tools on Linux, macOS and WSL: sdk install maven installs the latest Maven and configures PATH for you. It is most useful when different projects need different Maven or JDK versions - you switch with one command instead of editing environment variables.

# install SDKMAN
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

sdk install maven            # latest stable version
sdk list maven               # available versions
sdk install maven 3.10.0     # a specific version
sdk use maven 3.10.0         # switch in the current terminal
sdk default maven 3.10.0     # set the default version

SDKMAN can install the JDK as well (sdk list java, then sdk install java with an identifier from the list), and it sets JAVA_HOME automatically.

Verify the Installation: mvn -version

The mvn -version command (or mvn -v) confirms that Maven is installed correctly: it prints the Maven version, the installation directory (Maven home) and the JDK Maven runs on. If the output shows the expected Maven version and a path to a JDK rather than a JRE, the installation is complete.

mvn -version

# Sample output on Windows (your versions and paths will differ):
Apache Maven 3.10.0 (...)
Maven home: C:\dev\apache-maven-3.10.0
Java version: 21.0.5, vendor: Eclipse Adoptium, runtime: C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot
Default locale: en_US, platform encoding: UTF-8
OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

What to look at in the output:

• Apache Maven - the version that actually runs. If it is older than expected, another installation comes earlier in PATH; check with where mvn (Windows) or which mvn (Linux, macOS).
• Maven home - where Maven runs from. On Linux after apt install it is /usr/share/maven.
• Java version / runtime - the JDK Maven runs on. Its javac compiles your project, even if java -version in the same terminal reports a different version.

Typing mvn with no arguments is not an installation error - Maven works, it just does not know what to do:

mvn
# Output (fragment):
[ERROR] No goals have been specified for this build. You must specify a valid lifecycle phase or a goal ...

And mvn package in a folder without pom.xml ends with The goal you specified requires a project to execute but there is no POM in this directory - change to the project root first.

Common Installation Errors and How to Fix Them

Most problems after installing Maven come down to three causes: the bin directory is not on PATH, JAVA_HOME points to the wrong place, or the terminal was opened before the variables were changed. The error message almost always tells you which one it is.

Installing Maven vs the mvn install Command

"Installing Maven" means putting the tool itself on your computer, as described above. The mvn install command has nothing to do with that: it is a build lifecycle phase that compiles and tests your project, packages it into a jar and copies the result into the local repository ~/.m2/repository so that your other projects can use it as a dependency.

mvn install
# Output (fragment):
[INFO] Installing /home/user/hello-maven/pom.xml to /home/user/.m2/repository/com/examclouds/hello-maven/1.0-SNAPSHOT/hello-maven-1.0-SNAPSHOT.pom
[INFO] Installing /home/user/hello-maven/target/hello-maven-1.0-SNAPSHOT.jar to /home/user/.m2/repository/com/examclouds/hello-maven/1.0-SNAPSHOT/hello-maven-1.0-SNAPSHOT.jar
[INFO] BUILD SUCCESS

To just build a jar, mvn package is enough - the file appears in the target directory. The difference between the package, install and deploy phases, why running one phase also runs all the previous ones, and how the local repository is organized are covered in separate lessons of this module on the Maven build lifecycle and Maven repositories.