How to Install Apache Maven on Debian

Install Apache Maven on Debian to manage Java builds, dependencies, and documentation through a standardized project structure. Whether you need to compile Java applications, manage library dependencies automatically, or integrate with continuous integration and continuous delivery (CI/CD) pipelines like Jenkins, Maven provides the foundation for reproducible builds. By the end of this guide, you will have a working Maven installation verified with a test project.

Choose Your Apache Maven Installation Method

Before installing, consider your options. Debian offers Maven through its default repositories, while the Apache project provides the latest release for manual installation. The table below compares both approaches:

Method	Channel	Version	Updates	Best For
APT Package Manager	Debian Repos	Distribution default	Automatic via apt upgrade	Most users who prefer distro-tested packages
Manual Installation	Apache Downloads	Latest stable	Manual re-download	Users needing the newest Maven features

We recommend the APT method for most users because it provides automatic security updates and handles Java dependencies automatically. Only install manually if you specifically need features from the latest Maven release.

Maven versions differ by Debian release. Debian 13 currently ships Maven 3.9.9 with Java 21, Debian 12 ships Maven 3.8.7 with Java 17, and Debian 11 ships Maven 3.6.3 with Java 11. If you need a newer Maven version than your Debian release provides, use the manual installation method and confirm your version with mvn -version.

Method 1: Install Apache Maven via APT Package Manager

Step 1: Update Debian System Packages

First, refresh the package index so APT sees the latest Maven and Java packages:

sudo apt update

Specifically, running apt update refreshes your package index, ensuring you install the latest available version rather than a cached older release.

If you want to apply pending security updates now, run sudo apt upgrade before continuing.

Step 2: Install Apache Maven

Next, install Maven and the default Java Development Kit (JDK) so you have the compiler needed for builds:

sudo apt install maven default-jdk

The Maven package pulls in a Java runtime, but the JDK adds the javac compiler that Maven uses to build projects.

Step 3: Verify Maven and the Java Compiler

Once installation completes, verify that Maven is accessible and check the installed version:

mvn -version

Expected output (Debian 13):

Apache Maven 3.9.9
Maven home: /usr/share/maven
Java version: 21.0.9, vendor: Debian, runtime: /usr/lib/jvm/java-21-openjdk-amd64

Your output may include additional lines for locale and OS details.

Confirm the Java compiler is available:

javac -version

Expected output (Debian 13):

javac 21.0.9

The outputs above reflect Debian 13. Debian 12 uses Java 17 and Debian 11 uses Java 11, so your version numbers will match your release.

Method 2: Install Apache Maven from the Binary Tarball

Alternatively, this method downloads the latest Maven release directly from Apache and installs it under /opt, giving you access to newer features before they appear in Debian repositories.

Step 1: Install Prerequisites

Maven requires a Java Development Kit (JDK). Additionally, minimal Debian installations often omit curl and CA certificates, so install the prerequisites first:

sudo apt update
sudo apt install default-jdk ca-certificates curl

The JDK provides java and javac, ca-certificates enables HTTPS downloads, and curl fetches the release metadata and tarball.

Once you install the packages, verify that Java is available:

java -version

Expected output (Debian 13):

openjdk version "21.0.9" 2025-10-21
OpenJDK Runtime Environment (build 21.0.9+10-Debian-1deb13u1)
OpenJDK 64-Bit Server VM (build 21.0.9+10-Debian-1deb13u1, mixed mode, sharing)

Debian 12 uses Java 17 and Debian 11 uses Java 11, so your output will reflect your release.

Step 2: Download the Latest Maven Release

Now, use the GitHub API to detect the latest Maven release and download the tarball from Apache. Keep this terminal open because the MAVEN_VERSION variable is reused in the next steps:

cd /tmp
MAVEN_VERSION=$(curl -fsSL https://api.github.com/repos/apache/maven/releases/latest | grep -oP '"tag_name": "maven-\K[^"]+')
if [ -z "$MAVEN_VERSION" ]; then
  echo "Error: Could not determine the latest Maven version."
else
  curl -fL "https://dlcdn.apache.org/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz" -o "apache-maven-${MAVEN_VERSION}-bin.tar.gz"
fi

This command queries the Apache Maven GitHub releases for the latest tag and downloads the matching archive from the official CDN. The -f flag makes curl fail on HTTP errors, -L follows redirects, and -o saves the tarball using the versioned filename.

If the GitHub API request fails, set MAVEN_VERSION manually from the Apache Maven download page or the GitHub releases page, then re-run the download line.

If you want more examples of curl usage, see our curl command guide.

Step 3: Extract Maven to the Installation Directory

Next, extract the archive to /opt/, which is the standard location for optional software on Linux systems:

sudo tar xzf "apache-maven-${MAVEN_VERSION}-bin.tar.gz" -C /opt/

In this command, the -C flag specifies the target directory for extraction. If you closed your terminal, re-run the previous step so MAVEN_VERSION is set again.

Step 4: Create a Symbolic Link

After extraction, create a symbolic link to simplify path references and make future upgrades easier:

sudo ln -sfn /opt/apache-maven-${MAVEN_VERSION} /opt/maven

As a result, this creates a /opt/maven symlink pointing to the extracted directory. The -s flag creates a symlink, -f replaces any existing one, and -n treats the current symlink as a normal file, which keeps upgrades consistent even when multiple Maven versions are present.

Step 5: Configure Environment Variables

Now, create a profile script to set the required environment variables system-wide:

sudo tee /etc/profile.d/maven.sh >/dev/null <<'EOF'
export M2_HOME=/opt/maven
export PATH="${M2_HOME}/bin:${PATH}"
EOF

This command writes /etc/profile.d/maven.sh with two environment variables: M2_HOME points to the Maven installation, and PATH includes the Maven binaries. The quoted heredoc keeps the variables literal so each new shell expands them correctly.

Step 6: Apply the Environment Changes

System-wide profile scripts load during login sessions. To apply the changes immediately without opening a new terminal, reload /etc/profile:

source /etc/profile

Alternatively, log out and back in, or open a new terminal window for the changes to take effect automatically. The environment variables persist for all future sessions.

Step 7: Verify the Manual Installation

Finally, confirm that you correctly installed Maven and can access it from your PATH:

mvn -version

Expected output (Debian 13):

Apache Maven 3.9.12 (848fbb4bf2d427b72bdb2471c22fced7ebd9a7a1)
Maven home: /opt/maven
Java version: 21.0.9, vendor: Debian, runtime: /usr/lib/jvm/java-21-openjdk-amd64

The output confirms Maven home is /opt/maven (the symlink you created) and shows the Java version being used.

Debian 12 shows Java 17 and Debian 11 shows Java 11 in the version line, but the Maven home path remains /opt/maven across releases.

Before creating a project, confirm the Java compiler is available with javac -version because Maven uses it to compile sources.

Create a Test Maven Project

To verify your Maven installation works correctly, try creating and building a simple Java project.

Step 1: Generate a New Project

Maven provides archetypes (project templates) to quickly scaffold new projects. Create a basic Java application:

mvn archetype:generate -DgroupId=com.example.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

As a result, this command creates a new directory called my-app with a standard Maven project structure, including a pom.xml configuration file and sample Java source code.

Step 2: Build the Project

Next, navigate into the project directory and compile the application:

cd my-app
mvn package

During this process, Maven downloads required dependencies, compiles the source code, runs tests, and packages the application into a JAR file in the target/ directory.

Step 3: Run the Application

Finally, execute the compiled application to confirm everything works:

java -cp target/my-app-1.0-SNAPSHOT.jar com.example.app.App

Expected output:

Hello World!

This output confirms your Maven installation is fully functional and ready for Java development.

Configure Maven Proxy Settings (Optional)

If you build Maven projects behind a corporate proxy, configure ~/.m2/settings.xml so Maven can download dependencies.

Open the settings file in your preferred editor (nano shown below):

mkdir -p ~/.m2
nano ~/.m2/settings.xml

Replace the placeholders below with your proxy details:

<settings>
  <proxies>
    <proxy>
      <id>corporate-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.example.com</host>
      <port>8080</port>
    </proxy>
  </proxies>
</settings>

Save the file, then re-run the Maven command that failed to confirm dependencies download correctly.

Troubleshooting Common Maven Issues

JAVA_HOME Not Set or Incorrect

If Maven reports that JAVA_HOME is missing or incorrect, it cannot locate the JDK:

The JAVA_HOME environment variable is not defined correctly,
this environment variable is needed to run this program.

Check the current variable and the actual Java path:

printf 'JAVA_HOME=%s\n' "$JAVA_HOME"
readlink -f /usr/bin/java

Expected output (Debian 13 example):

JAVA_HOME=/bad
/usr/lib/jvm/java-21-openjdk-amd64/bin/java

Set JAVA_HOME system-wide and reload the login profile:

echo "export JAVA_HOME=/usr/lib/jvm/default-java" | sudo tee /etc/profile.d/java-home.sh
source /etc/profile

Verify Maven can locate Java:

mvn -version

Expected output (Debian 13, manual install example):

Apache Maven 3.9.12 (848fbb4bf2d427b72bdb2471c22fced7ebd9a7a1)
Maven home: /opt/maven
Java version: 21.0.9, vendor: Debian, runtime: /usr/lib/jvm/java-21-openjdk-amd64

If you installed Maven with APT, Maven home will be /usr/share/maven and the version may differ by release.

Maven Command Not Found

If your shell reports that mvn is missing after a manual install, the PATH update has not been applied:

bash: line 1: mvn: command not found

Check whether the Maven binary exists and whether it is in your PATH:

command -v mvn || echo "mvn not found in PATH"
ls -l /opt/maven/bin/mvn

Expected output (Debian 13 example):

mvn not found in PATH
-rwxr-xr-x 1 root root 6184 Dec 13 09:16 /opt/maven/bin/mvn

Reload the system profile or open a new terminal window:

source /etc/profile

Verify the command works:

mvn -version

Expected output (Debian 13, manual install example):

Apache Maven 3.9.12 (848fbb4bf2d427b72bdb2471c22fced7ebd9a7a1)
Maven home: /opt/maven
Java version: 21.0.9, vendor: Debian, runtime: /usr/lib/jvm/java-21-openjdk-amd64

Update Apache Maven

Update APT-Installed Maven

For APT installations, update Maven along with other system packages:

sudo apt update
sudo apt install --only-upgrade maven

Update Manually Installed Maven

However, for manual installations, download the latest release and refresh the symbolic link:

cd /tmp
if ! command -v curl >/dev/null || ! command -v tar >/dev/null; then
  echo "Install curl and tar before updating: sudo apt install curl tar"
else
  MAVEN_VERSION=$(curl -fsSL https://api.github.com/repos/apache/maven/releases/latest | grep -oP '"tag_name": "maven-\K[^"]+')
  if [ -z "$MAVEN_VERSION" ]; then
    echo "Error: Could not determine the latest Maven version."
  else
    curl -fL "https://dlcdn.apache.org/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz" -o "apache-maven-${MAVEN_VERSION}-bin.tar.gz"
    sudo tar xzf "apache-maven-${MAVEN_VERSION}-bin.tar.gz" -C /opt/
    sudo ln -sfn /opt/apache-maven-${MAVEN_VERSION} /opt/maven
    mvn -version
  fi
fi

This sequence detects the newest Maven release tag, downloads it from the Apache CDN, extracts to /opt/, and updates the symlink. The -f and -L flags ensure curl fails fast on HTTP errors and follows redirects.

Do not automate Maven upgrades with cron. Review release notes and test builds before updating production environments.

Remove Apache Maven

Remove APT-Installed Maven

To uninstall Maven installed via APT:

sudo apt remove maven
sudo apt autoremove

Subsequently, the autoremove command cleans up Java and other dependencies that APT automatically installed with Maven and no longer needs.

Verify the removal by checking for the Maven command:

command -v mvn || echo "mvn not found"

Expected output:

mvn not found

Remove Manually Installed Maven

The following commands permanently delete the Maven installation directory. Only proceed if you no longer need your manual Maven installation.

The -rf flags remove directories recursively and without prompting, so double-check the paths before you run them.

For manual installations, remove the installation directory, symbolic link, and environment script:

sudo rm -rf /opt/apache-maven-*
sudo rm -f /opt/maven
sudo rm -f /etc/profile.d/maven.sh

If you created a dedicated JAVA_HOME profile script while troubleshooting, remove it as well:

sudo rm -f /etc/profile.d/java-home.sh

After removal, open a new terminal or run hash -r to clear the command cache.

Remove Maven User Data (Optional)

The following command permanently deletes your Maven configuration, cached dependencies, and local repository. This includes downloaded JAR files and custom settings. Only proceed if you no longer need this data.

The -rf flags remove the directory recursively without prompting, so confirm you no longer need the cached dependencies.

If desired, you can also remove the local Maven repository containing cached dependencies and configuration:

rm -rf ~/.m2

Conclusion

You now have Apache Maven configured on Debian for building Java projects and managing dependencies. Whether you chose the APT package for automatic updates or manually installed the latest release, Maven handles the complete build lifecycle from compilation through testing to packaging. For version control integration, see how to install Git on Debian. To containerize your Maven builds, explore installing Docker on Debian.