Skip to main content

TP1.2 — Installing Maven 3.9.x

Objectives​

This practical work will allow you to:

  • Install Apache Maven 3.9.x on your operating system
  • Configure the necessary environment variables
  • Verify that the installation works correctly
  • Understand the role of Maven in a Spring Boot project

Estimated duration: 30-45 minutes

Why Maven?​

Apache Maven is the standard build tool for Java and Spring Boot projects. It manages:

  • Dependencies: automatic downloading of necessary libraries
  • Build: compilation, tests, application packaging
  • Lifecycle: clean → compile → test → package → install → deploy
Your Java code  ──►  Maven  ──►  Ready application (.jar)
                        │
                        ├── Downloads dependencies
                        ├── Compiles code
                        ├── Runs tests
                        └── Creates the .jar file
Recommended version

We use Maven 3.9.x for its optimal compatibility with Java 17+ and Spring Boot 3.x.

Prerequisites​

Before installing Maven, you must have Java JDK 17 or higher installed.

Verify Java​

java -version

Expected result (example):

openjdk version "17.0.x" 2024-xx-xx
OpenJDK Runtime Environment ...
OpenJDK 64-Bit Server VM ...

If Java is not installed, check our detailed guide:

👉 TP: Installing Java JDK 17

Or download it directly from:

Installation on Windows​

Step 1: Download Maven​

  1. Go to https://maven.apache.org/download.cgi
  2. Download the Binary zip archive file: apache-maven-3.9.9-bin.zip
Direct link

apache-maven-3.9.9-bin.zip

If version 3.9.9 is no longer available, take the latest 3.9.x version from the download page.

Step 2: Extract the archive​

  1. Create a folder C:\Program Files\Maven (or C:\maven)
  2. Extract the ZIP content into this folder
  3. You should have: C:\Program Files\Maven\apache-maven-3.9.9
C:\Program Files\Maven\
└── apache-maven-3.9.9\
    ├── bin\
    │   ├── mvn.cmd        ← The Maven executable
    │   └── mvnDebug.cmd
    ├── boot\
    ├── conf\
    │   └── settings.xml
    └── lib\

Step 3: Configure the MAVEN_HOME variable​

  1. Open the Start menu → type "environment variables"
  2. Click on "Edit the system environment variables"
  3. Click on "Environment Variables..."
  4. In System variables, click on New:
    • Variable name: MAVEN_HOME
    • Variable value: C:\Program Files\Maven\apache-maven-3.9.9
  5. Click on OK

Step 4: Add Maven to PATH​

  1. In System variables, find the Path variable
  2. Click on Edit
  3. Click on New
  4. Add: %MAVEN_HOME%\bin
  5. Click on OK to close all windows

Step 5: Verify the installation​

Close all open terminals, then open a new terminal (CMD or PowerShell):

mvn -version

Expected result:

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: C:\Program Files\Maven\apache-maven-3.9.9
Java version: 17.0.x, vendor: Eclipse Adoptium
Default locale: fr_CA, platform encoding: UTF-8
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
Important

If mvn is not recognized after configuring the PATH, restart your terminal or even your computer. Environment variables are not reloaded in already open terminals.

Windows Alternative: Installation with Chocolatey​

If you have Chocolatey installed, the installation is simpler:

choco install maven --version=3.9.9

Windows Alternative: Installation with Scoop​

If you have Scoop installed:

scoop install maven

Installation on macOS​

Homebrew is the most popular package manager on macOS.

Install Homebrew (if not already done):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Maven:

brew install maven

Verify:

mvn -version
tip

Homebrew automatically installs the latest stable version of Maven 3.9.x and configures the PATH for you.

Option 2: Manual Installation​

Step 1: Download Maven​

cd ~/Downloads
curl -O https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz

Step 2: Extract the archive​

sudo mkdir -p /opt/maven
sudo tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt/maven

Step 3: Configure environment variables​

Open your shell profile file:

For zsh (macOS default since Catalina):

nano ~/.zshrc

For bash:

nano ~/.bash_profile

Add the following lines at the end of the file:

# Apache Maven
export MAVEN_HOME=/opt/maven/apache-maven-3.9.9
export PATH=$MAVEN_HOME/bin:$PATH

Save (Ctrl+O, Enter, Ctrl+X), then reload the profile:

source ~/.zshrc

Step 4: Verify​

mvn -version

Expected result:

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /opt/maven/apache-maven-3.9.9
Java version: 17.0.x, vendor: Eclipse Adoptium
...
OS name: "mac os x", ...

Option 3: SDKMAN!​

SDKMAN! is a tool that manages versions of Java, Maven, Gradle, etc.

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

# Install Maven
sdk install maven 3.9.9

Installation on Linux​

Option 1: Package Manager (Ubuntu/Debian)​

sudo apt update
sudo apt install maven
Attention to the version

Official Ubuntu/Debian repositories may contain an old version of Maven. Check the installed version:

mvn -version

If the version is lower than 3.9, prefer the manual installation below.

Step 1: Download Maven​

cd /tmp
wget https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz

Step 2: Extract and install​

sudo mkdir -p /opt/maven
sudo tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt/maven

Step 3: Configure environment variables​

Create a Maven configuration file:

sudo nano /etc/profile.d/maven.sh

Add the following content:

#!/bin/bash
export MAVEN_HOME=/opt/maven/apache-maven-3.9.9
export PATH=$MAVEN_HOME/bin:$PATH

Make the file executable and load it:

sudo chmod +x /etc/profile.d/maven.sh
source /etc/profile.d/maven.sh

Step 4: Verify​

mvn -version

Expected result:

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /opt/maven/apache-maven-3.9.9
Java version: 17.0.x, vendor: Eclipse Adoptium
...
OS name: "linux", ...

Option 3: SDKMAN! (also works on Linux)​

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

sdk install maven 3.9.9

Option 4: Fedora / CentOS / RHEL​

sudo dnf install maven

Final Verification (all OS)​

After installation, open a new terminal and run these commands:

# Verify Java
java -version

# Verify Maven
mvn -version

# Verify that JAVA_HOME is set
echo $JAVA_HOME       # macOS/Linux
echo %JAVA_HOME%      # Windows CMD
$env:JAVA_HOME        # Windows PowerShell

Expected Result​

You should see:

  • Java: version 17 or higher
  • Maven: version 3.9.x
  • JAVA_HOME: points to your JDK installation
If JAVA_HOME is not set

Maven requires the JAVA_HOME variable. If it is not set:

Windows: Add JAVA_HOME in the system environment variables, pointing to your JDK folder (e.g., C:\Program Files\Eclipse Adoptium\jdk-17.0.x)

macOS/Linux: Add in your ~/.zshrc or ~/.bashrc:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)   # macOS
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 # Linux (path may vary)

Test Maven: First Build​

To confirm that Maven works, let's create a test project:

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

If Maven downloads dependencies and displays BUILD SUCCESS, your installation is complete.

cd test-maven
mvn clean package
[INFO] BUILD SUCCESS
[INFO] Total time:  X.XXX s

You can delete this test folder:

cd ..
rm -rf test-maven       # macOS/Linux
rmdir /s /q test-maven   # Windows CMD

Summary of Commands by OS​

ActionWindowsmacOS (Homebrew)Linux (Manual)
InstallDownload ZIP + configure PATHbrew install mavenwget + extract + PATH
Configure PATHSystem environment variablesAutomatic/etc/profile.d/maven.sh
Verifymvn -versionmvn -versionmvn -version
UpdateRedownloadbrew upgrade mavenRedownload

Troubleshooting​

mvn is not recognized​

CauseSolution
PATH not configuredAdd MAVEN_HOME/bin to PATH
Terminal not reloadedClose and reopen the terminal
Wrong pathCheck that the Maven bin folder exists at the configured path

JAVA_HOME is not defined correctly​

CauseSolution
JAVA_HOME not setSet the JAVA_HOME environment variable
JAVA_HOME points to JREPoint to the JDK (not the JRE)
Space in the pathUse quotes: "C:\Program Files\Java\jdk-17"

Maven downloads slowly​

The first Maven build downloads many dependencies into the ~/.m2/repository folder. This is normal and only happens once.

Validation Checklist​

Before moving to Module 2, ensure everything is in place:

  • Java 17+ installed and java -version works
  • Maven 3.9.x installed and mvn -version works
  • JAVA_HOME is set correctly
  • The mvn archetype:generate test worked
  • Visual Studio Code installed with Java extensions

Next Steps​

Your environment is ready! You can now move to Module 2:

➡️ Module 2: Getting Started with Spring Boot

⬅️ Back to Module 1