Table of Contents

URL: https://www.progressiverobot.com/install-maven-mac-os/

Introduction

Apache Maven is a project management tool used for building and managing software projects, primarily those written in Java. It standardizes the build process through a central piece of information called the Project Object Model (POM), an XML file that describes the project's configuration and dependencies. Maven's main functions are build automation and dependency management. It automates tasks like compiling code, running tests, and packaging applications into distributable formats. For dependency management, Maven automatically downloads and manages the libraries a project needs from a central repository, which helps avoid version conflicts and simplifies project setup. These features make it a fundamental tool in the Java ecosystem for creating consistent and reproducible builds.

This tutorial provides step-by-step instructions for installing Apache Maven on a macOS system. The guide begins by covering the prerequisite of installing a Java Development Kit (JDK), which is required for Maven to run. It then details three different installation methods: using the Homebrew package manager, using SDKMAN!, or performing a manual installation from the official binaries. After the installation, you will learn how to verify that Maven is configured correctly and test its functionality by creating and building a sample project. Finally, the article includes sections for troubleshooting common installation problems and for uninstalling Maven if needed.

Key Takeaways:

  • Maven is a Java-based tool, so you must have a Java Development Kit (JDK) installed as a prerequisite.
  • You can install Maven on macOS using three primary methods: the Homebrew package manager, SDKMAN!, or a manual download and configuration.
  • For most users, installing with Homebrew is the recommended approach because it automatically manages the installation, updates, and path configuration.
  • After any installation, you should verify it was successful by running the mvn -v command in your terminal to check the version.
  • A manual installation gives you full control over the version and location but requires you to set the MAVEN_HOME and PATH environment variables yourself.
  • The most common installation issue, "command not found," is typically fixed by correctly configuring your system's PATH variable in your shell profile.
  • Creating and building a sample project using mvn package is the best way to confirm that your Maven setup is fully functional.

Prerequisites

maven illustration for: Prerequisites

Before you begin this guide, you need to have the following:

  • A computer running macOS with administrator access, as many of the commands require sudo to install software in system-wide directories.
  • Homebrew (Recommended): The easiest way to install Maven and its dependencies is with the Homebrew package manager. If you don't have it installed, you can check out this article on how to install Homebrew on macOS
  • A Java Development Kit (JDK): Maven is a Java application and requires a JDK (version 8 or later) to run. A Java Runtime Environment (JRE) is not sufficient, as Maven needs the development tools included in the JDK. This guide provides a step for installing a JDK if you do not have one.

Step 1 — Checking if Maven is Already Installed

Before starting the installation, check if Maven is already present on your system. Some development tools or previous setups might have already installed it.

Open your terminal and run the following command:

				
					mvn -v

If Maven is installed, the output will display its version, the location of your Maven installation, and the Java version it is using.

Example Output:

				
					Apache Maven 3.9.11 (cf0109cc29...)
Maven home: /opt/homebrew/Cellar/maven/3.9.11/libexec
Java version: 17.0.8, vendor: Homebrew, runtime: /opt/homebrew/Cellar/openjdk@17/17.0.8/libexec/openjdk.jdk/Contents/Home
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "14.2.1", arch: "aarch64", family: "mac"

If you see an output similar to this, Maven is already installed, and you can proceed to [Step 5 — Testing Maven with a Sample Project](#step-5–testing-maven-with-a-sample-project) to verify its functionality.

If the command returns zsh: command not found: mvn or a similar message, Maven is not installed or not configured in your system's PATH. Proceed to the next step.

Step 2 — Installing Java (A Maven Prerequisite)

Maven requires a JDK to run. This guide uses OpenJDK, an open-source implementation of the Java Platform. The simplest way to install OpenJDK on macOS is with Homebrew. If you don't have Homebrew installed, check out our How to install and use Homebrew on macOS guide for installation instructions.

First, update your Homebrew package list to ensure you get the latest version available:

				
					brew update

Next, install OpenJDK. The following command installs the latest long-term support (LTS) version:

				
					brew install openjdk

After the installation is complete, you need to set the JAVA_HOME environment variable. This variable points to the location of your JDK installation, which other tools like Maven use.

For Zsh (the default shell on modern macOS versions), add the following line to your ~/.zshrc file:

				
					export JAVA_HOME=$(/usr/libexec/java_home)

If you use Bash, add the same line to your ~/.bash_profile or ~/.bashrc file.

Apply the changes to your current terminal session by running:

				
					source ~/.zshrc

Verify that Java is installed correctly by checking its version:

				
					java -version

You should see output detailing the installed OpenJDK version. With Java installed, you are now ready to install Maven.

Step 3 — Installing Maven on macOS

There are several ways to install Maven on macOS. Using a package manager like Homebrew or a version manager like SDKMAN! is generally recommended because they handle setup and updates automatically.

Method Description Best For
Homebrew The most common package manager for macOS. It handles installation, updates, and PATH configuration automatically. Most users looking for a simple, one-time setup.
SDKMAN! A command-line tool for managing multiple Software Development Kit versions on Unix-based systems. Developers who need to switch between different Maven or Java versions.
Manual Involves downloading the binary archive from the official Apache site and configuring environment variables yourself. Users who require a specific version not available through package managers or need a portable installation.

Option 1: Installing Maven with Homebrew (Recommended)

Installing Maven with Homebrew is the most direct method. It requires only one command.

In your terminal, run:

				
					brew install maven

Homebrew will download the latest stable version of Maven, install it, and configure the necessary environment variables. No further configuration is needed.

Option 2: Installing Maven with SDKMAN

SDKMAN! is a tool for managing parallel versions of multiple SDKs. It's useful if you work on different projects that require specific versions of Maven.

First, install SDKMAN! if you don't already have it:

				
					curl -s "https://get.sdkman.io" | bash

Follow the on-screen instructions to complete the installation. Once that is done, run the following command in the same terminal or a new one:

				
					source "$HOME/.sdkman/bin/sdkman-init.sh"

Once SDKMAN! is installed, you can install Maven with a single command:

				
					sdk install maven

SDKMAN! will download and install the latest stable version of Maven and set it as the default. To install a specific version, you can run sdk list maven to see the available versions and then sdk install maven <version>.

Option 3: Installing Maven Manually

Manual installation gives you complete control over the installation location and version.

  1. Download the Maven Binary: Navigate to the Apache Maven download page and download the binary zip archive (e.g., apache-maven-3.9.11-bin.zip).
  1. Extract the Archive: Once the download is complete, extract the archive. It's common practice to place third-party software in /usr/local/. You can create a directory for it and extract the contents there.

First, create the directory:

				
					 sudo mkdir -p /usr/local/apache-maven

Next, extract the downloaded archive to this new directory. Replace ~/Downloads/apache-maven-3.9.11-bin.zip with the actual path to your downloaded file.

				
					 sudo unzip ~/Downloads/apache-maven-3.9.11-bin.zip -d /tmp &amp;&amp; sudo mv /tmp/apache-maven-3.9.11/* /usr/local/apache-maven/

The --strip-components=1 flag removes the top-level directory from the archive, placing the contents directly into /usr/local/apache-maven.

  1. Configure Environment Variables: For the manual installation to work, you must set the environment variables manually:
  1. Open Your Shell Configuration File: If you use Zsh (default), open ~/.zshrc. If you use Bash, open ~/.bash_profile.
				
					 nano ~/.zshrc
  1. Set MAVEN_HOME and Update the PATH: Add the following lines to the file. These lines define where Maven is located and add its bin directory to your system's PATH.
				
					 # Maven Environment Variables
 export MAVEN_HOME=/usr/local/apache-maven
 export PATH=$MAVEN_HOME/bin:$PATH
  1. Apply the Changes: Save and close the file. To apply the changes to your current terminal session, run the source command:
				
					 source ~/.zshrc

Step 4 — Verifying the Maven Installation

After installing Maven using any of the methods, verify that it was installed correctly. Run the same command you used in the initial check:

				
					mvn -v

If the installation was successful, you will see output that shows the Apache Maven version, the Maven home directory, and the Java version it uses. If you used Homebrew or SDKMAN!, the path should point to their installation directories. If you installed it manually, the path should reflect the directory you configured.

Step 5 — Testing Maven with a Sample Project

A good way to confirm that Maven is fully functional is to use it to create and build a new project. Maven provides a tool called archetype to generate project templates.

  1. Generate a Sample Project: In your terminal, navigate to a directory where you want to create a test project (e.g., your home directory or a projects folder). Run the following command:
				
					 mvn archetype:generate -DgroupId=com.example -DartifactId=myapp -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

This command downloads the maven-archetype-quickstart template and generates a simple Java project in a new directory named myapp.

  1. Build the Project: Navigate into the newly created project directory:
				
					 cd myapp

Inside, you'll find a pom.xml file, which is the core configuration file for a Maven project.

Now, build the project using the package command. The first time you run this, Maven will download the necessary dependencies from the central repository.

				
					 mvn package

If the build completes successfully, you will see a [INFO] BUILD SUCCESS message in the output. A target directory will be created, containing the compiled code and a JAR file named myapp-1.0-SNAPSHOT.jar. This confirms that your Maven installation is working correctly.

Step 6 — Uninstalling Maven (Optional)

If you need to remove Maven from your system, the process depends on how it was installed.

  • Homebrew:
				
					 brew uninstall maven
  • SDKMAN!:
				
					 sdk uninstall maven
  • Manual Installation:
  1. Remove the directory where you extracted Maven:
				
					 sudo rm -rf /usr/local/apache-maven
  1. Open your ~/.zshrc or ~/.bash_profile file and remove the MAVEN_HOME and PATH export lines that you added.

Troubleshooting Common Installation Issues

Even with a straightforward installation process, you might encounter issues. This section details common problems and provides direct solutions to get Maven running correctly on your system.

mvn: command not found

This is the most frequent error, indicating that your terminal cannot find the Maven executable.

  • Cause: The directory containing the mvn binary is not included in your system's PATH variable. The PATH tells your shell where to look for commands. This issue is common with manual installations or if a package manager's setup script did not complete correctly.
  • Fix:
  1. First, confirm that Maven is actually installed. If you used a package manager, you can check with one of these commands:
				
					 # For Homebrew
 brew list maven

 # For SDKMAN!
 sdk list maven
  1. If you installed Maven manually, the problem is almost always in your shell configuration file (~/.zshrc for Zsh or ~/.bash_profile for Bash). Open the file and ensure these two lines are present and correct:
				
					 export MAVEN_HOME=/usr/local/apache-maven
 export PATH=$MAVEN_HOME/bin:$PATH
  1. After adding or correcting these lines, you must reload the configuration for the changes to take effect in your current terminal session.
				
					 source ~/.zshrc

Wrong Java Version Detected

Maven is built with Java and requires a JDK to run, not just a Java Runtime Environment (JRE).

  • Cause: Your system might have multiple Java installations, and Maven could be defaulting to an older or incompatible version. The JAVA_HOME environment variable, which tells Maven which JDK to use, may be unset or pointing to the wrong location.
  • Fix:
  1. The recommended approach is to install a modern JDK using Homebrew.
				
					 brew install openjdk
  1. Next, set the JAVA_HOME variable correctly in your ~/.zshrc file. The following command dynamically finds the location of the highest version JDK managed by macOS.
				
					 export JAVA_HOME=$(/usr/libexec/java_home)
  1. After sourcing your .zshrc file, confirm that both Java and Maven are configured correctly.
				
					 java -version
 mvn -v

The output of mvn -v should show the Java version you just configured.

Multiple Maven Installations Conflicting

Having more than one version of Maven installed (e.g., one via Homebrew and another downloaded manually) can cause conflicts.

  • Cause: Your system's PATH variable might contain entries for two different Maven installations, and the shell is executing an older or unintended version.
  • Fix:
  1. Identify which Maven executable is currently being used by your system.
				
					 which mvn

The command will output the full path to the mvn command, for example, /opt/homebrew/bin/mvn or /usr/local/apache-maven/bin/mvn.

  1. Decide which installation you want to keep and remove the other one.
				
					 # To remove a Homebrew version
 brew uninstall maven

 # To remove a manual version (adjust path if needed)
 sudo rm -rf /usr/local/apache-maven
  1. Ensure that only the path to your desired Maven installation remains in your PATH variable within your shell configuration file.

Homebrew Maven Not Linking Properly

Homebrew uses symbolic links (symlinks) to make software available in your PATH. Sometimes this linking process can fail.

  • Cause: After running brew install maven, the symlink that makes the mvn command available globally may not have been created correctly, often due to file conflicts or permission issues.
  • Fix:
  1. You can manually force Homebrew to create the necessary links.
				
					 brew link maven
  1. If the link command fails, it will usually report a conflict. Run Homebrew's built-in diagnostic tool for a detailed report and suggested fixes.
				
					 brew doctor

SDKMAN! Not Initialized

After installing SDKMAN!, it may not be available in your current terminal session.

  • Cause: The SDKMAN! installation script modifies your shell configuration file, but these changes are not automatically loaded into the terminal session that you used for the installation.
  • Fix:
  1. To make SDKMAN! available immediately, run its initialization script manually.
				
					 source "$HOME/.sdkman/bin/sdkman-init.sh"
  1. Alternatively, the simplest solution is to close your current terminal window and open a new one. The new session will correctly load the updated configuration.

Permission Issues in Manual Installation

When installing software manually into system-level directories like /usr/local/, you may encounter permission errors.

  • Cause: Your standard user account does not have the necessary permissions to write to protected system directories.
  • Fix:
  1. Use the sudo command to execute the extraction command with administrative privileges. This gives the command permission to write files to the target directory.
				
					 sudo tar -xzf apache-maven-3.9.11-bin.tar.gz -C /usr/local/
  1. After extraction, you can also ensure your user account has ownership of the directory to avoid future permission problems, though this is often not necessary.

[info] Pro Tip: Always verify your final setup with mvn -v. This single command confirms that the mvn executable is in your PATH and that it can correctly identify your configured JDK, ensuring both Maven and its primary dependency are ready for use.

FAQs

1. How do I install Maven on macOS using Homebrew?

Installing Maven with Homebrew is the most straightforward method. It handles the download, installation, and path configuration in one step.

First, make sure Homebrew is up to date:

				
					brew update

Then, run the install command:

				
					brew install maven

Homebrew will install Maven and its dependencies and automatically add it to your system's PATH.

2. How do I manually install Maven on Mac?

Manual installation gives you more control over the version and location.

  1. Download Maven: Go to the official Apache Maven download page and download the "binary zip archive" file (e.g., apache-maven-x.x.x-bin.zip).
  1. Extract the Archive: Move the downloaded file to your desired installation directory and unzip it. A common location is /usr/local/.
				
					 # Example: Move and extract to /usr/local/apache-maven
 sudo mkdir -p /usr/local/apache-maven
 sudo unzip ~/Downloads/apache-maven-*-bin.zip -d /tmp
 sudo mv /tmp/apache-maven-*/apache-maven-*/* /usr/local/apache-maven/
  1. Set Environment Variables: After extracting, you must manually configure your environment variables for the system to find Maven.

3. How do I set environment variables for Maven on macOS?

After a manual installation, you need to tell your shell where to find the Maven executable.

  1. Edit Shell Profile: Open your shell's configuration file. For most modern macOS users, this is ~/.zshrc.
				
					 nano ~/.zshrc
  1. Add Path Exports: Add the following lines to the end of the file, which define Maven's location and add its bin directory to your executable PATH.
				
					 export MAVEN_HOME=/usr/local/apache-maven
 export PATH=$MAVEN_HOME/bin:$PATH

*Note: Adjust /usr/local/apache-maven if you extracted Maven to a different directory.*

  1. Apply Changes: Save the file and reload your shell configuration to apply the changes.
				
					 source ~/.zshrc

4. How do I verify if Maven is installed correctly?

Regardless of the installation method, you can verify that Maven is working with a single command. Open a new terminal window and run:

				
					mvn -v

If the installation was successful, the output will display the installed Apache Maven version, the Maven home directory, and the Java version it is using.

Example Output:

				
					Apache Maven 3.9.11 (...)
Maven home: /opt/homebrew/Cellar/maven/3.9.11/libexec
Java version: 17.0.8, vendor: Homebrew...

5. Do I need Java JDK installed to use Maven?

Yes. Maven is a Java-based application and requires a JDK to execute its build processes. A Java Runtime Environment alone is not sufficient, as Maven needs the compiler and other tools included in the full JDK.

6. How do I update Maven on macOS?

Updating Maven depends on how you originally installed it.

  • If you used Homebrew, you can update Maven to the latest version with a single command:
				
					 brew upgrade maven
  • If you used SDKMAN!, the process involves two steps. First, update SDKMAN! itself, then upgrade the Maven package:
				
					 # Update SDKMAN! first
 sdk selfupdate

 # Upgrade the Maven installation
 sdk upgrade maven
  • If you installed it manually, you must repeat the manual installation process with the newer version. Download the new binary archive from the Maven website, extract it to your chosen directory (e.g., /usr/local/apache-maven, overwriting the old files), and your MAVEN_HOME and PATH environment variables will automatically point to the new version.

Conclusion

In this article, we detailed three methods for installing Apache Maven on macOS: using Homebrew, SDKMAN!, and a manual setup. For most development work, using a package manager like Homebrew or SDKMAN! is the suggested approach because it simplifies both the initial installation and future updates. With Maven configured on your system, you are prepared to manage the build process for Java applications consistently. You can now handle dependency management, compilation, and packaging for your projects.