A Comprehensive Guide to Setting Up Apache Maven

In this guide, you’ll learn everything you need to know about Apache Maven—from what it is to how to configure it across different operating systems.


What is Apache Maven?

In simple terms, Maven is a powerful build and project management tool primarily used by Java developers. Compared to older build systems like Apache Ant, Maven provides a standardized way to manage builds, dependencies, and project lifecycles.

Key Features of Maven:

  • Simplifies the build process.
  • Ensures consistency with a uniform build system.
  • Manages project dependencies through a central or local repository.
  • Provides quality project information.
  • Follows development best practices.
  • Allows for smooth migration to new features.

Now, let’s dive into how to install and configure Maven on your system.


Step 1: Downloading Apache Maven

  1. Visit the official Apache Maven Download page.
  2. Download the binary archive matching your operating system:
    • .zip for Windows
    • .tar.gz for Linux/macOS
  3. Extract the archived files to a directory of your choice:
    • On Windows, you might extract to: C:\Apache\apache-maven-<version>
    • On Linux/macOS, extract it to: /opt/apache-maven-<version>

Step 2: Configuring Environment Variables

After downloading Maven, the next step is to configure your environment so that Maven can be accessed from your terminal or command prompt.

On Windows:

  1. Open System Properties:
    • Right-click on “This PC” → select Properties → click Advanced System Settings → select Environment Variables.
  2. Add the following system variables:
    • M2_HOME: Set this to the Maven installation directory (e.g., C:\Apache\apache-maven-<version>).
    • JAVA_HOME: Set this to your JDK installation directory (e.g., C:\Program Files\Java\jdk-<version>).
  3. Add M2_HOME\bin to your PATH variable:
    • Locate and edit the PATH variable in the Environment Variables list.
    • Append: ;%M2_HOME%\bin

On Linux/macOS:

  1. Open your shell profile configuration file. This depends on the shell you’re using:
    • For bash: ~/.bashrc or ~/.bash_profile
    • For zsh (default on macOS): ~/.zshrc
  2. Add the following lines to configure Maven and Java:
    export M2_HOME=/opt/apache-maven-<version>
    export PATH=$M2_HOME/bin:$PATH
    export JAVA_HOME=/path/to/your/jdk
    

    Example:

    export M2_HOME=/opt/apache-maven-3.9.5
    export PATH=$M2_HOME/bin:$PATH
    export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
    
  3. Reload the configuration:
    source ~/.bashrc    # For bash users
    source ~/.zshrc     # For zsh users
    

Step 3: Verifying the Installation

Now that Maven is installed and configured, it’s time to check if it works correctly.

  1. Open a terminal or command prompt.
  2. Run the following command:
    mvn -version
    
  3. You should see output similar to this:
    Apache Maven 3.x.x (...)
    Maven home: <Maven installation path>
    Java version: <your JDK version>, vendor: Oracle Corporation
    Java home: <JDK path>
    

Additional Installation Options

Using a Package Manager (Optional):

If you’re on Linux or macOS, you may install Maven using a package manager. Note that these methods may not always install the latest version.

  1. Linux (Ubuntu/Debian):
    sudo apt update
    sudo apt install maven
    
  2. Linux (CentOS/RHEL):
    sudo yum install maven
    
  3. macOS:
    Install Maven via Homebrew:

    brew install maven
    

Verifying Java:

Maven requires a JDK (Java Development Kit) to work. Verify that Java is installed by running:

java -version

If it’s not installed:

  • On Linux, install OpenJDK:
    sudo apt install openjdk-17-jdk   # For Ubuntu/Debian
    sudo yum install java-17-openjdk  # For CentOS/RHEL
    
  • On macOS, install OpenJDK via Homebrew:
    brew install openjdk
    

Step 4: Running Maven

You’re now ready to use Maven! Here are a few common commands:

  1. Check Maven Version:
    mvn -version
    
  2. Create a New Maven Project:
    mvn archetype:generate
    
  3. Build a Maven Project:
    mvn clean install
    

Final Thoughts

Congratulations! You’ve successfully installed and configured Apache Maven. With Maven set up on your system, you can now manage your Java projects with ease. Maven simplifies build processes, ensures consistent project management, and makes dependency management seamless. Feel free to explore its many features and extend your knowledge by diving into Maven’s powerful tools, plugins, and architecture.

Have fun coding! 🚀

How do I compile and execute a JDK preview features with Maven?

To compile and execute a JDK preview features with Maven, you need to add in the following configurations in your pom.xml file:

  • Compiler Plugin: The configuration should specify the JDK version and enable the preview features. It should look similar to this:
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <release>21</release>
                <compilerArgs>--enable-preview</compilerArgs>
            </configuration>
        </plugin>
    </plugins>
</build>
  • Surefire Plugin: If you’re using the Maven Surefire Plugin to run your tests, you should also enable the preview features there. The configuration may look similar to this:
<build>
    <plugins>
    ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>2.22.2</version>
            <configuration>
                <argLine>--enable-preview</argLine>
            </configuration>
        </plugin>
    </plugins>
</build>

Before building your project, ensure that you have JDK 21-preview installed on your computer, and it’s properly set in JAVA_HOME environment variable or in the IDE settings.

Then use Maven to package or install your project:

mvn clean package
# or
mvn clean install

Please ensure that you have the correct version of maven-compiler-plugin and maven-surefire-plugin that support the JDK 21-preview features. For the project that uses Spring MVC, you should make sure all dependencies are compatible with JDK 21-preview as well.

How do I install third-party libraries in Maven repository?

Sometimes when the required libraries / dependencies is not available in the Maven Central Repository we need to manually install it to our local repository. This library must be placed in the correct directory in our local repository to enable Maven to find it. The default location is under the ${user.home}/.m2/repository.

To make this job easier Maven provides a maven-install-plugin that will help us to install the third-party library in the correct place. The following command shows how to do it.

The long command

mvn install:install-file -Dfile=<path-to-file> -DgroupId=<group-id> \
        -DartifactId=<artifact-id> -Dversion=<version> -Dpackaging=<packaging>

Where:

  • -Dfile = path to the third-party library file
  • -DgroupId = the groupId of the library
  • -DartifactId = the artifactId of the library
  • -Dversion = the version number of the library
  • -Dpackaging = the library packaging

An example to install an Oracle JDBC library to your local repository is:

mvn install:install-file -Dfile=ojdbc7.jar -DgroupId=com.oracle \
        -DartifactId=ojdbc7 -Dversion=12.1.0.2 -Dpackaging=jar

The simple command

If you have the pom.xml file, you can install it with the following command:

mvn install:install-file \
        -Dfile=<path-to-file> \
        -DpomFile=<path-to-pomfile>

Where:

  • -Dfile = path to the third-party library file
  • -DpomFile = the location to the library pom.xml file

Starting with the Maven version 2.5 you can use even a simpler command. When the library is build by Maven, a pom.xml file will be placed under the META-INF directory. This pom.xml file will be used by default when we install the library. To install a library all you need is the following command:

mvn install:install-file -Dfile=<path-to-file>

How to use Google Maven Central mirror?

The following configuration will use Google’s mirror of the Maven Central repository. Alter your ${M2_HOME}/conf/settings.xml or ${user.home}/.m2/settings.xml to add the mirror as seen in the following configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<settings>
    .
    .
    <mirrors>
        <mirror>
            <id>google-maven-central</id>
            <name>Google Maven Central</name>
            <url>https://maven-central.storage.googleapis.com</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>
    .
    .
</settings>

How to configure a proxy in Maven settings?

When we work behind a proxy server, we need to configure Maven to be able to connect to the internet. To enable proxy we can configure Maven settings.xml file, either in ${M2_HOME}/conf/settings.xml or ${user.home}/.m2/settings.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<settings>
    .
    .
    <proxies>
        <proxy>
            <id>my-proxy</id>
            <active>true</active>
            <protocol>http</protocol>
            <host>proxy.example.org</host>
            <port>8080</port>
            <username>username</username>
            <password>password</password>
            <nonProxyHosts>*.example.org|*.example.com</nonProxyHosts>
        </proxy>
    </proxies>
    .
    .
</settings>

The <proxy> element in the configuration above contains the information about the proxy server. These include information about the host, port, username and password. Set these elements to match your proxy server configuration.