How to Create an Executable JAR with Dependencies Using Maven: A Step-by-Step Guide

Packaging your Java project into a single executable JAR file with all dependencies is essential for easy distribution and deployment. In this guide, you’ll learn how to use Maven plugins like maven-assembly-plugin, maven-shade-plugin, and others to bundle dependencies into a runnable JAR file. Whether you’re a developer or DevOps engineer, these methods ensure your application runs smoothly without classpath issues.

Why Create an Executable JAR with Dependencies?

An executable JAR (Java ARchive) that includes all dependencies simplifies deployment by:

• Eliminating manual dependency management.
• Ensuring consistency across environments.
• Allowing execution via java -jar your-app.jar.

Method 1: Using Maven Assembly Plugin

The maven-assembly-plugin is a simple solution for packaging dependencies into a single JAR.

Step 1: Configure the Plugin in pom.xml

<build>
  <plugins>
    <plugin>
      <artifactId>maven-assembly-plugin</artifactId>
      <configuration>
        <archive>
          <manifest>
            <mainClass>com.example.Main</mainClass> <!-- Your main class -->
          </manifest>
        </archive>
        <descriptorRefs>
          <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
      </configuration>
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>single</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Step 2: Build the JAR

Run:

mvn clean package

The executable JAR will be generated at target/your-app-jar-with-dependencies.jar.

Pros:

• Simple setup.
• Automatically binds to the Maven package phase.

Cons:

• No class relocation (conflicting dependencies may cause issues).

Method 2: Using Maven Shade Plugin for Advanced Packaging

The maven-shade-plugin provides more flexibility, including class relocation and resource merging.

Step 1: Add the Plugin in pom.xml

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <transformers>
          <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
            <mainClass>com.example.Main</mainClass>
          </transformer>
        </transformers>
      </configuration>
    </execution>
  </executions>
</plugin>

Step 2: Build the JAR

Run:

mvn clean package

Find the shaded JAR at target/your-app-shaded.jar.

Pros:

• Supports class relocation to avoid conflicts.
• Merges resource files (e.g., META-INF).

Cons:

• Configuration can be complex for large projects.

Method 3: Using Spring Boot Maven Plugin

For Spring Boot projects, the spring-boot-maven-plugin simplifies the creation of a fat JAR.

Configuration in pom.xml

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <executions>
    <execution>
      <goals>
        <goal>repackage</goal>
      </goals>
      <configuration>
        <mainClass>com.example.Main</mainClass>
      </configuration>
    </execution>
  </executions>
</plugin>

Build the JAR

Run:

mvn clean package

The output JAR (target/your-app.jar) includes embedded dependencies and is executable.

Method 4: Manual Dependency Management

If you prefer external dependencies (not bundled in the JAR), use the maven-dependency-plugin to copy dependencies to a /lib folder and update the manifest classpath.

Step 1: Copy Dependencies

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <id>copy-dependencies</id>
      <phase>prepare-package</phase>
      <goals>
        <goal>copy-dependencies</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.build.directory}/lib</outputDirectory>
      </configuration>
    </execution>
  </executions>
</plugin>

Step 2: Configure the JAR Manifest

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <configuration>
    <archive>
      <manifest>
        <addClasspath>true</addClasspath>
        <classpathPrefix>lib/</classpathPrefix>
        <mainClass>com.example.Main</mainClass>
      </manifest>
    </archive>
  </configuration>
</plugin>

Run the JAR

java -jar target/your-app.jar

FAQ: Common Questions Answered

1. Which plugin is best for Uber JARs?

• maven-shade-plugin: Ideal for complex projects needing class relocation.
• maven-assembly-plugin: Best for simple projects.
• Spring Boot Plugin: Perfect for Spring-based apps.

2. How do I fix “No main manifest attribute” errors?

Ensure the <mainClass> in your plugin configuration matches your application’s entry point.

3. Can I exclude specific dependencies?

Yes! Use <excludes> in the maven-shade-plugin or maven-assembly-plugin configurations.

Conclusion

Creating an executable JAR with dependencies in Maven is straightforward with the right plugin:

• Basic projects: Use maven-assembly-plugin.
• Advanced needs: Opt for maven-shade-plugin.
• Spring Boot apps: Leverage spring-boot-maven-plugin.

Choose the method that aligns with your project’s requirements and simplify your deployment workflow today!