How to Install Apache Maven on Debian

Apache Maven simplifies Java project management by handling builds, dependencies, and documentation through a standardized project structure. Whether you need to compile Java applications, manage library dependencies automatically, or integrate with 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 vary by Debian release: Debian 11 provides Maven 3.6.3, Debian 12 provides Maven 3.8.7, and Debian 13 provides Maven 3.9.9. If you need a newer version than your Debian release offers, use the manual installation method.

Method 1: Install Apache Maven via APT Package Manager

Step 1: Update Debian System Packages

First, refresh the package index and upgrade existing packages to ensure your system has the latest security patches:

sudo apt update && sudo apt upgrade

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

Step 2: Install Apache Maven

Next, install Maven along with its Java dependencies using APT:

sudo apt install maven

This command installs Maven and automatically pulls in the default Java Development Kit (JDK) as a dependency. As a result, you do not need to install Java separately when using the APT method.

Step 3: Verify the Maven Installation

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

mvn -version

Expected output (Debian 13):

Apache Maven 3.x.x
Maven home: /usr/share/maven
Java version: x.x.x, vendor: Debian, runtime: /usr/lib/jvm/java-xx-openjdk-amd64
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "x.x.x", arch: "amd64", family: "unix"

Your version numbers will differ based on your Debian release. Debian 12 shows Maven 3.8.7 with Java 17, while Debian 11 shows Maven 3.6.3 with Java 11.

Method 2: Install Apache Maven Manually from Source

Alternatively, this method downloads the latest Maven release directly from Apache, giving you access to the newest features before they appear in Debian repositories.

Step 1: Install Prerequisites

Maven requires Java to run. Additionally, minimal Debian installations omit curl and wget by default. Install all prerequisites:

sudo apt install default-jdk curl wget

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

java -version

Expected output (Debian 13):

openjdk version "x.x.x" yyyy-mm-dd
OpenJDK Runtime Environment (build x.x.x+xx-Debian-x)
OpenJDK 64-Bit Server VM (build x.x.x+xx-Debian-x, mixed mode, sharing)

Step 2: Download the Latest Maven Release

Now, use the GitHub API to automatically fetch and download the latest Maven release. This command detects the current version and downloads directly from Apache:

cd /tmp
MAVEN_VERSION=$(curl -s https://api.github.com/repos/apache/maven/releases/latest | grep -oP '"tag_name": "maven-\K[^"]+') && wget "https://dlcdn.apache.org/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz"

This command queries the Apache Maven GitHub repository for the latest release tag, then constructs and downloads the corresponding binary archive from the official Apache CDN.

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-*.tar.gz -C /opt/

In this command, the -C flag specifies the target directory for extraction. Additionally, using a wildcard pattern (*) means you do not need to update this command when newer versions are released.

Step 4: Create a Symbolic Link

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

sudo ln -sf /opt/apache-maven-*/ /opt/maven

As a result, this creates a /opt/maven symlink pointing to the extracted directory. Consequently, when upgrading, you only need to update this symlink rather than modifying environment variables.

Step 5: Configure Environment Variables

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

echo -e "export M2_HOME=/opt/maven\nexport PATH=\${M2_HOME}/bin:\${PATH}" | sudo tee /etc/profile.d/maven.sh

This command creates /etc/profile.d/maven.sh with two environment variables: M2_HOME points to the Maven installation, and the script extends PATH to include the Maven binaries.

Step 6: Apply the Environment Changes

To apply the changes immediately without opening a new terminal, reload the profile script:

source /etc/profile.d/maven.sh

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:

Apache Maven 3.x.x
Maven home: /opt/maven
Java version: x.x.x, vendor: Debian, runtime: /usr/lib/jvm/java-xx-openjdk-amd64
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "x.x.x", arch: "amd64", family: "unix"

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

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.

Troubleshooting Common Maven Issues

JAVA_HOME Not Set Error

If Maven reports that you have not set JAVA_HOME or it points to an invalid location, check your Java installation:

echo $JAVA_HOME
which java

If JAVA_HOME is empty, you can fix this by adding the following line to /etc/profile.d/maven.sh:

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

Maven Command Not Found

If your system does not recognize the mvn command after manual installation, the PATH variable may not contain the correct value. Verify the environment:

echo $M2_HOME
echo $PATH | grep maven

If these return empty or incorrect values, source the profile script again or open a new terminal session:

source /etc/profile.d/maven.sh

Proxy Configuration for Corporate Networks

When working behind a corporate proxy, Maven may fail to download dependencies. In this case, configure proxy settings in ~/.m2/settings.xml:

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

Then, add the following content, replacing the placeholder values 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>

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, use the automated download to fetch the latest version and update the symbolic link:

cd /tmp
MAVEN_VERSION=$(curl -s https://api.github.com/repos/apache/maven/releases/latest | grep -oP '"tag_name": "maven-\K[^"]+') && wget "https://dlcdn.apache.org/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz"
sudo tar xzf apache-maven-*.tar.gz -C /opt/
sudo rm /opt/maven
sudo ln -sf /opt/apache-maven-*/ /opt/maven
mvn -version

This script automatically detects the newest Maven release, downloads it, extracts to /opt/, and updates the symlink. The wildcard pattern in the symlink command handles any version number.

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:

which mvn

If removal succeeded, this command produces no output.

Remove Manually Installed Maven

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

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

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

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

Remove Maven User Data (Optional)

Warning: 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.

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.