Installing Maven

This chapter walks you through installing Maven on Windows, macOS, and Linux. By the end, you will have a working Maven installation tied to JDK 21, and you will know how to verify it and fix common setup problems.

Prerequisites

• JDK 21 installed and configured
• Administrator or superuser access (for some installation methods)
• A working internet connection

Windows Installation

Step 1: Download Maven

Visit the official Maven download page and grab the latest binary ZIP archive. At the time of writing, Maven 3.9.x is the recommended stable line. You want the file named something like apache-maven-3.9.x-bin.zip.

Step 2: Extract the Archive

Extract the ZIP to a permanent location. A good choice is a dedicated tools folder on a non-system drive, such as D:\tools\maven. Keeping it off the C: drive avoids permission headaches and makes reinstallation easier if you ever wipe the operating system.

After extraction, your directory should look like this:

D:\tools\maven\
  bin\
  boot\
  conf\
  lib\
  LICENSE
  NOTICE
  README.txt

Step 3: Set Environment Variables

Open the Start menu, search for "Environment Variables," and select Edit the system environment variables.

Click Environment Variables, then under System variables click New to create MAVEN_HOME:

Next, find the Path variable in the same list, click Edit, and add a new entry:

%MAVEN_HOME%\bin

Step 4: Verify the Installation

Open a new Command Prompt or PowerShell window and run:

mvn -version

You should see output similar to this:

Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
Maven home: D:\tools\maven
Java version: 21.0.2, vendor: Oracle Corporation, runtime: D:\Java\jdk-21

Common Windows Issues

macOS Installation

Option A: Homebrew (Recommended)

Homebrew is the simplest and cleanest way to install Maven on macOS. If you do not have Homebrew installed, visit brew.sh for a one-line install script.

Open Terminal and run:

# Install Maven through Homebrew
brew install maven

After installation finishes, verify it:

mvn -version

Check that the Java version in the output is 21. If you see an older version, you likely have multiple JDKs installed. Set the correct one by adding this line to your shell profile (~/.zshrc or ~/.bash_profile):

# Point JAVA_HOME to JDK 21
export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Then reload your profile:

source ~/.zshrc

Run mvn -version again to confirm.

Option B: Manual Installation

If you prefer not to use Homebrew, download the binary tar.gz from the official Maven website and extract it:

# Extract the archive to /opt (requires sudo)
sudo tar -xzf apache-maven-3.9.x-bin.tar.gz -C /opt/
 
# Create a symbolic link for easier updates
sudo ln -s /opt/apache-maven-3.9.x /opt/maven

Add the bin directory to your PATH by editing ~/.zshrc:

# Add Maven to PATH
export PATH="/opt/maven/bin:$PATH"

Reload your profile and verify:

source ~/.zshrc
mvn -version

Linux Installation

Debian and Ubuntu (apt)

Open a terminal and run:

# Update package index
sudo apt update
 
# Install Maven
sudo apt install maven

Verify the installation:

mvn -version

Fedora and RHEL (dnf)

On Fedora, RHEL, CentOS Stream, and related distributions:

# Install Maven
sudo dnf install maven

Verify with mvn -version.

Option: SDKMAN (Multi-Version Management)

SDKMAN is a fantastic tool for managing multiple versions of Java build tools on Linux (and macOS). If you think you will need to switch between Maven versions, this is the way to go.

Install SDKMAN:

# Install SDKMAN
curl -s "https://get.sdkman.io" | bash
 
# Load SDKMAN into the current shell
source "$HOME/.sdkman/bin/sdkman-init.sh"

Install Maven through SDKMAN:

# List available Maven versions
sdk list maven
 
# Install the latest stable version
sdk install maven 3.9.6
 
# Set it as the default
sdk default maven 3.9.6

Switching versions later is trivial:

# Switch to a different installed version
sdk use maven 3.8.8

Verifying Your Setup

Regardless of your operating system, the final check is the same. Run:

mvn -version

You should see four critical pieces of information:

1. Maven version — should be 3.9.x or later
2. Maven home — the directory where Maven is installed
3. Java version — must be 21 for this tutorial
4. Java home — the JDK installation Maven is using

If any of these look wrong, trace back to the relevant section above and double-check your environment variables.

Uninstalling or Upgrading

FAQ

Do I need to install Maven if I only use IntelliJ IDEA?

Technically no, but practically yes. IntelliJ bundles a version of Maven, but for reproducible builds and CI/CD pipelines, you want a standalone installation that matches exactly. We will show you how to configure IntelliJ to use your system Maven in the next chapter.

Can I have multiple versions of Maven installed?

Yes. On Windows, keep each version in its own folder and switch by changing MAVEN_HOME. On macOS and Linux, SDKMAN handles this effortlessly.

Why does mvn -version show Java 17 (or 8) instead of 21?

Maven respects the JAVA_HOME environment variable. If it points to an older JDK, that is what Maven will use. Update JAVA_HOME to your JDK 21 path and restart your terminal.

Is there a way to install Maven without admin privileges?

Yes. Download the binary archive and extract it to a folder inside your home directory (for example, ~/tools/maven). Then add ~/tools/maven/bin to your user PATH. No sudo or admin rights required.

What is the difference between Maven 3.8 and 3.9?

Maven 3.9 includes performance improvements, better HTTP repository handling, and updated dependencies. For learning purposes, either version works fine, but 3.9 is the recommended current line.