Building a JAR with Dependencies in Maven: A Step-by-Step Guide for Beginners

"Your application only works in the IDE? Time to fix that!"

If you've ever written in Java, you've likely encountered this situation: you proudly show your friend your new project, run it in IntelliJ IDEA or Eclipse — everything works perfectly. But as soon as you hand the project to a colleague or try to run it from the command line — you're greeted with ClassNotFoundException or NoClassDefFoundError. Sound familiar?

Most training courses and tutorials show how to create a JAR file using Maven, but they often miss one important detail: where do the dependencies go?. A regular JAR file contains only your code, while all libraries (e.g., Apache Commons, Jackson, JUnit) are left out. This is why millions of Java developers ask the question on Stack Overflow: "How can I create an executable/runnable JAR with dependencies using Maven?"

In this article, we'll cover several proven ways to build an executable JAR with dependencies using Maven. You'll learn how to configure maven-assembly-plugin, maven-shade-plugin, and even how it works in Spring Boot. Let's go!

Why doesn't a regular JAR work?

Let's do a simple experiment. Imagine you have an application that parses JSON using the Jackson library. You create a regular JAR with the command mvn package, and then try to run it:

java -jar my-app.jar

And you get something like:

Exception in thread "main" java.lang.NoClassDefFoundError: com/fasterxml/jackson/databind/ObjectMapper

Why does this happen? Because Maven by default packages only your compiled code (classes from the src/main/java folder). All dependencies you specified in pom.xml remain in the local Maven repository (~/.m2/repository). When you run the JAR, the JVM doesn't know where to find these libraries and throws an error.

The solution is to create a fat JAR (or uber JAR), which contains not only your classes but also all necessary dependencies. This is exactly what special Maven plugins are for.

Method 1: maven-assembly-plugin (simple and reliable)

The most popular and simple way is to use maven-assembly-plugin. It creates a JAR where all dependencies are unpacked and merged with your classes. Let's configure it.

Add the following code to your pom.xml in the <build><plugins> section:

<plugin>\n    <groupId>org.apache.maven.plugins</groupId>\n    <artifactId>maven-assembly-plugin</artifactId>\n    <version>3.6.0</version>\n    <configuration>\n        <descriptorRefs>\n            <descriptorRef>jar-with-dependencies</descriptorRef>\n        </descriptorRefs>\n        <archive>\n            <manifest>\n                <mainClass>com.example.Main</mainClass>\n            </manifest>\n        </archive>\n    </configuration>\n    <executions>\n        <execution>\n            <id>make-assembly</id>\n            <phase>package</phase>\n            <goals>\n                <goal>single</goal>\n            </goals>\n        </execution>\n    </executions>\n</plugin>

Important: replace com.example.Main with the full name of your class containing the main method.

Now build the project with the command:

mvn clean package

In the target folder, two files will appear:

\n
• my-app.jar — the regular