sodcalculator

10 Tech How-To

Install Maven on Mac: Step-by-Step Guide

Guide 10-12516 · Updated · Step by step

To install Maven on a Mac, you need a Java Development Kit (JDK) and then you can install Maven using Homebrew, SDKMAN, or by downloading the binary from the Apache Maven project. The easiest method is with Homebrew: run brew install maven in Terminal, then verify with mvn -version. This guide covers all three methods, including setup steps, common issues, and how to configure Maven for your projects.

What Is Maven and Why Do You Need It?

Maven is a build automation and project management tool primarily used for Java projects. It handles compilation, packaging, dependency management, and documentation generation based on a Project Object Model (POM) file. Instead of manually downloading JAR files and configuring classpaths, Maven downloads dependencies from central repositories and manages versions for you. If you work on Java applications, especially with frameworks like Spring, Maven (or its alternative Gradle) is essential for reproducible builds.

Prerequisites: Install Java JDK

Maven requires Java to run, but it does not bundle a JDK. You must install a JDK (version 8 or later, though Maven 3.9+ requires Java 8+; Maven 4 requires Java 17+). The easiest way is via Homebrew:

  1. Install Homebrew if you haven’t: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Install a JDK, for example OpenJDK 21: brew install openjdk@21
  3. Add the JDK to your PATH (Homebrew will show the exact command after install).

Alternatively, download a JDK from Adoptium or Oracle. Verify Java with java -version in Terminal.

Method 1: Install Maven with Homebrew (Recommended)

Homebrew is the most popular package manager for macOS and simplifies installation and updates.

  1. Open Terminal.
  2. Run: brew install maven
  3. Wait for the installation to finish. It may take a few minutes.
  4. Verify: mvn -version – you should see Maven version, Java version, and OS info.

Homebrew installs Maven to /usr/local/Cellar/maven (Intel) or /opt/homebrew/Cellar/maven (Apple Silicon) and symlinks it into /usr/local/bin or /opt/homebrew/bin, which should already be in your PATH.

Method 2: Install Maven with SDKMAN

SDKMAN is a version manager for Java-related tools, ideal if you need multiple Maven versions.

  1. Install SDKMAN: curl -s "https://get.sdkman.io" | bash
  2. Open a new Terminal or run source "$HOME/.sdkman/bin/sdkman-init.sh"
  3. Install Maven: sdk install maven
  4. Choose a version if prompted, or install a specific one: sdk install maven 3.9.9
  5. Verify: mvn -version

SDKMAN keeps versions in ~/.sdkman/candidates/maven and switches between them with sdk use maven 3.9.9.

Method 3: Manual Installation from Apache

If you prefer a manual setup or need a specific version, download the binary archive from the Apache Maven project website (maven.apache.org).

  1. Download the apache-maven-3.9.9-bin.tar.gz file (or latest).
  2. Open Terminal and navigate to your Downloads folder.
  3. Extract: tar -xzf apache-maven-3.9.9-bin.tar.gz
  4. Move it to a permanent location: sudo mv apache-maven-3.9.9 /usr/local/
  5. Set environment variables. Open your shell profile (~/.zshrc for zsh, ~/.bash_profile for bash) and add:
export M2_HOME=/usr/local/apache-maven-3.9.9
export PATH=$M2_HOME/bin:$PATH
  1. Reload: source ~/.zshrc (or reopen Terminal).
  2. Verify: mvn -version

Make sure the extracted folder name matches the path you set.

How to Verify and Configure Maven

After installation, run mvn -version to confirm. The output shows Maven home, Java version, and OS. If you get “command not found”, your PATH is not set correctly. For Homebrew, ensure /usr/local/bin or /opt/homebrew/bin is in PATH.

Maven uses a settings file at ~/.m2/settings.xml for global configuration (mirrors, proxies, local repository location). By default, the local repository is ~/.m2/repository where all dependencies are cached. You can create the settings file to customize, but it’s optional for basic use.

Common Problems and How to Fix Them

  • mvn: command not found – PATH not set. For Homebrew, run brew info maven to see the install path and add it to PATH.
  • Java version error – Maven requires a JDK, not a JRE. Install a full JDK and ensure JAVA_HOME is set. Add export JAVA_HOME=$(/usr/libexec/java_home) to your shell profile.
  • Permission denied – If using manual install, you may need to change ownership: sudo chown -R $(whoami) /usr/local/apache-maven-3.9.9
  • Maven uses wrong Java version – Set JAVA_HOME to the desired JDK path before running Maven.
  • Slow downloads or connection issues – Check your network/proxy. You can configure mirrors in settings.xml to use a faster repository.

Frequently Asked Questions

Do I need to install Java before Maven?

Yes, Maven is a Java application and requires a JDK. Without Java, Maven won’t run. Install any JDK (8 or later) and set JAVA_HOME.

What is the difference between Maven and Gradle?

Both are build tools. Maven uses XML-based POM files and a fixed lifecycle, while Gradle uses Groovy/Kotlin DSL and is more flexible and often faster. Maven is older and more widely used in enterprise, Gradle is popular for Android and new projects.

How do I uninstall Maven?

If installed via Homebrew: brew uninstall maven. Via SDKMAN: sdk uninstall maven. Manual: delete the folder and remove the PATH lines from your shell profile.

Where does Maven store downloaded dependencies?

In your local repository, typically ~/.m2/repository. You can change this location in settings.xml with the localRepository element.

How do I create a new Maven project?

Run mvn archetype:generate -DgroupId=com.example -DartifactId=myapp -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false. This creates a basic Java project structure with a POM file.

Next Steps and Best Practices

Once Maven is installed, you can start using it immediately. For a new project, use the mvn archetype:generate command. For existing projects, navigate to the directory containing pom.xml and run mvn clean install to build. Keep your Maven version updated via Homebrew or SDKMAN. Also, consider using an IDE like IntelliJ IDEA or Eclipse, which integrate Maven and can import projects directly. Remember to set JAVA_HOME correctly if you have multiple JDKs installed.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →