How to install Maven Manually on macOS Monterey

Apache Maven is the most widely used Java build tool. macOS does not ship Maven pre-installed, so you need to add it yourself — either manually from the official download or through Homebrew. This guide covers both approaches, plus how to set up your shell environment so the mvn command is available in every terminal session.

Prerequisites

Maven requires a JDK. Verify Java is installed before proceeding:

java -version
# java version "21.0.2" 2024-01-16 LTS

If this fails, install a JDK first (e.g., from Adoptium or via brew install openjdk). Maven 3.9+ requires Java 8 or later; Maven 4.x requires Java 17 or later.

Option 1: Manual Installation (Recommended for Version Control)

Step 1 — Download the Binary Archive

Go to the Apache Maven download page and grab the binary tar.gz for the latest stable release (3.9.x as of this writing). You can also download it directly from the terminal:

# Replace 3.9.6 with the current version from maven.apache.org/download
curl -O https://dlcdn.apache.org/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz

Step 2 — Extract to a Stable Location

Extract the archive to a directory you control. A dedicated runtime directory in your home folder keeps things tidy:

mkdir -p ~/DevRuntime
tar -xzf apache-maven-3.9.6-bin.tar.gz -C ~/DevRuntime
ls ~/DevRuntime/apache-maven-3.9.6/
# bin  boot  conf  lib  LICENSE  NOTICE  README.txt

Step 3 — Set MAVEN_HOME and Update PATH

macOS Catalina and later use Zsh as the default shell. Add environment variables to ~/.zshenv — this file is sourced for all shell sessions, including non-interactive ones started by IDEs and build pipelines:

# Open ~/.zshenv in any text editor, or append with echo:
echo 'export MAVEN_HOME="$HOME/DevRuntime/apache-maven-3.9.6"' >> ~/.zshenv
echo 'export PATH="$MAVEN_HOME/bin:$PATH"' >> ~/.zshenv

After editing, reload the file in your current shell:

source ~/.zshenv

Step 4 — Verify

mvn --version
# Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
# Maven home: /Users/yourname/DevRuntime/apache-maven-3.9.6
# Java version: 21.0.2, vendor: Eclipse Adoptium, runtime: /Library/Java/...
# Default locale: en_US, platform encoding: UTF-8
# OS name: "mac os x", version: "14.2", arch: "aarch64", family: "mac"

The output confirms Maven is on the PATH and shows which JDK it's using.

Option 2: Install via Homebrew

Homebrew is the simpler option if you don't need to manage multiple Maven versions:

brew install maven

Homebrew installs Maven to /opt/homebrew/opt/maven (Apple Silicon) or /usr/local/opt/maven (Intel) and adds it to your PATH automatically. Verify:

mvn --version
# Apache Maven 3.9.6

which mvn
# /opt/homebrew/bin/mvn

To upgrade later: brew upgrade maven. To see available versions: brew info maven.

Switching Between Multiple Maven Versions

If you need different Maven versions for different projects (e.g., Maven 3.6 for a legacy project, Maven 3.9 for a new one), the manual approach makes switching straightforward. Extract each version to its own subdirectory:

~/DevRuntime/
  apache-maven-3.6.3/
  apache-maven-3.9.6/

Then update MAVEN_HOME in ~/.zshenv to point at the version you want active, and source ~/.zshenv. Alternatively, use a version manager like sdkman, which handles Java and Maven versions together:

# Install sdkman (if not already installed)
curl -s "https://get.sdkman.io" | bash

# Install a specific Maven version
sdk install maven 3.9.6

# Switch to a different version
sdk use maven 3.6.3

The ~/.zshenv vs ~/.zshrc Difference

Using ~/.zshenv for MAVEN_HOME and PATH ensures your IDE (IntelliJ IDEA, VS Code) picks up the correct Maven even when it launches a non-interactive shell to run builds.

Running Your First Build

Once Maven is installed, create a simple project to confirm everything works end-to-end:

mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=hello-maven \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.4 \
  -DinteractiveMode=false

cd hello-maven
mvn package
java -cp target/hello-maven-1.0-SNAPSHOT.jar com.example.App
# Hello World!

Configuring the Local Repository

Maven downloads dependencies to ~/.m2/repository by default. To change this location (useful if your home directory is on a small SSD), edit ~/.m2/settings.xml:

<settings>
  <localRepository>/Volumes/FastDrive/.m2/repository</localRepository>
</settings>

Summary

To install Maven on macOS manually: download the binary archive, extract it to a stable directory like ~/DevRuntime, set MAVEN_HOME and update PATH in ~/.zshenv, then run source ~/.zshenv and verify with mvn --version. For a simpler one-command install, use brew install maven. Use ~/.zshenv (not ~/.zshrc) for environment variables so that IDEs and non-interactive shells also see the correct Maven installation.