Maven vs Gradle: Builds Demystified

You cloned a Java repo. The README says "just run the build," and the repo root contains a file you didn't write: pom.xml or build.gradle.kts. Your instinct from the Java Setup 2026 post is to reach for javac — but this project has twelve libraries, a test suite, and a src/main/java directory three levels deep. Hand-assembling the classpath already looks like this:

javac -cp lib/gson-2.10.jar:lib/slf4j-api-2.0.9.jar:lib/commons-lang3-3.14.0.jar \
  -d out $(find src -name '*.java')
java -cp out:lib/gson-2.10.jar:lib/slf4j-api-2.0.9.jar:lib/commons-lang3-3.14.0.jar com.acme.Main

That works exactly once. The moment someone adds a thirteenth library, updates a version, or asks "but does it pass the tests before it ships?", the hand-rolled commands rot. A build tool replaces all of this with one declared file and one command. It owns the whole pipeline — compile the sources, download the dependencies, run the tests, and package the result — and it does it the same way on your laptop and on the CI server. This post covers the two build tools that run the Java world: Maven, the convention-driven veteran, and Gradle, the fast, flexible challenger.

The problem a build tool solves

Strip away the branding and every Java build does the same five jobs:

Resolve dependencies — find the exact library versions the project needs, downloading them if necessary.
Compile — run javac over the sources with the right flags and the right classpath.
Test — run the test suite and fail the build if anything is red.
Package — bundle classes and resources into a distributable artifact, usually a .jar.
Repeat identically everywhere — the same inputs must produce the same result on every machine.

The build file (pom.xml for Maven, build.gradle.kts for Gradle) is the single source of truth for all five. You declare what the project needs; the tool figures out how:

Decision rule: if the repo already has a pom.xml, it's a Maven project; if it has build.gradle or build.gradle.kts, it's Gradle. Don't fight it — learn to drive the one in front of you. The rest of this post makes sure you can.

Maven: convention over configuration

Maven (3.9.x is the current line) is the older of the two, and its philosophy is convention over configuration: if you put your code where Maven expects it, you barely configure anything. Sources live in src/main/java, resources in src/main/resources, tests in src/test/java. Break the convention and you fight the tool; follow it and a twenty-line file builds a real project.

The pom.xml, decoded

pom.xml — the Project Object Model — has four things you must understand:

GAV coordinates (groupId, artifactId, version): your project's identity. com.acme:hello:1.0.0 is how the world refers to your artifact — the reverse-domain groupId avoids name collisions, the artifactId is the project name, the version is obvious. Other projects will depend on you using exactly these three.
Dependencies: the libraries you need, each identified by its GAV. Maven downloads them and puts them on the right classpaths.
Plugins: Maven itself does almost nothing — plugins do the work. The compiler plugin compiles, Surefire runs tests, the jar plugin packages. Many are bound to the lifecycle by default, so a minimal project needs no explicit plugin section at all.
Properties: named constants — Java version, encoding — referenced as ${...} so they change in one place.

Here is a complete, minimal, real pom.xml for a small app with one library dependency and JUnit 5:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- GAV: this project's coordinates -->
    <groupId>com.acme</groupId>
    <artifactId>hello</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>     <!-- a real dependency: Apache Commons Lang -->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.14.0</version>
        </dependency>
        <!-- JUnit 5: test-only, never ships in the jar -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.10.2</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

A matching tiny app, src/main/java/com/acme/App.java, plus a test at src/test/java/com/acme/AppTest.java (JUnit gets its own post — "JUnit 5 & Mockito: Testing That Catches Bugs" — later in this track):

// src/main/java/com/acme/App.java
package com.acme;

import org.apache.commons.lang3.StringUtils;

public class App {
    public static void main(String[] args) {
        String name = args.length > 0 ? args[0] : "world";
        System.out.println(StringUtils.capitalize("hello, " + name + "!"));
    }
}

// src/test/java/com/acme/AppTest.java
package com.acme;

import org.apache.commons.lang3.StringUtils;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertTrue;

class AppTest {
    @Test
    void commonsLangIsOnTheTestClasspath() {
        assertTrue(StringUtils.isNotBlank("hi"));
    }
}

Two details worth noticing: <scope>test</scope> means JUnit is on the classpath for compiling and running tests only — it never leaks into your production jar (scope misuse is trap #4). And there is no explicit compiler plugin here: Maven's default lifecycle bindings already attach the compiler plugin's compile goal to the compile phase. Convention doing its job.

The lifecycle: phases, not scripts

Maven builds are organized as a lifecycle — an ordered list of phases. The key insight: running a phase runs every phase before it. mvn package runs validate, then compile, then test, then package — in that order, always.

The phases after package matter too: verify runs integration checks, install copies your jar into the local repository (so other local projects can depend on it), and deploy pushes it to a shared remote repository. Decision rule: for day-to-day work, mvn package is the command — it compiles, tests, and jars. Reach for mvn verify when integration tests exist, and mvn install when another module on your machine needs this artifact (see the multi-module section).

Where jars come from: repositories

Maven resolves each dependency by checking two places, in order:

The local repository — ~/.m2/repository on your machine. A cache: if the exact version was downloaded before, Maven uses it without touching the network.
Remote repositories — Maven Central by default, the public warehouse of nearly every open-source Java library. Companies usually add an internal proxy (Artifactory or Nexus) in front of it for speed and control.

The first build of a project downloads the world; the second one is fast because the local repository is warm. This is also why release versions are immutable — 3.14.0 means the same bytes forever, so caching them is safe. That guarantee is exactly what SNAPSHOT versions break.

The wrapper: mvnw

Maven itself must be installed — and "Maven 3.8 on your laptop, Maven 3.9 on CI" is a real source of weird failures. The Maven wrapper fixes it: a tiny script checked into the repo that downloads and pins the right Maven version automatically. Generate it once:

mvn wrapper:wrapper
./mvnw package   # uses the pinned Maven, no local install needed

Commit mvnw, mvnw.cmd, and the .mvn/wrapper/ directory; then everyone — including CI — builds with the identical Maven. (The wrapper still needs a JDK; if it complains about JAVA_HOME, the setup post's trap #2 has the fix.)

Gradle: the fast, flexible challenger

Gradle (8.x/9.x is the current line) takes the opposite philosophy: your build is code. Instead of XML, you write the build in a real language — Kotlin DSL (build.gradle.kts) is the modern default; Groovy (build.gradle) is the legacy option you'll still see in older projects. Code means conditionals, loops, and functions in your build logic — more power, more rope.

Here is the exact equivalent of the Maven project above, in Kotlin DSL:

plugins {
    java
}

group = "com.acme"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.apache.commons:commons-lang3:3.14.0")
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
    }
}

tasks.withType<Test> {
    useJUnitPlatform()
}

Reading it piece by piece: the java plugin adds the standard Java conventions (same src/main/java layout as Maven) and the tasks below. repositories { mavenCentral() } is the Gradle twin of Maven's default remote. Dependencies use group:name:version shorthand — implementation means "needed to compile and run" (the default scope), testImplementation means "test classpath only" (Gradle's answer to Maven's test scope). The toolchain block tells Gradle to find or auto-provision a JDK 21 for compiling, independent of the JVM running Gradle itself. And useJUnitPlatform() switches the test task to the JUnit 5 engine — without it, Gradle would find no tests to run.

Tasks: Gradle's unit of work

Where Maven has phases, Gradle has tasks — named units of work wired into a dependency graph. ./gradlew build runs the build lifecycle task, which depends on check (runs test) and assemble (runs jar). Explore any project with:

./gradlew tasks --all   # every task, grouped, with descriptions

Decision rule: in Gradle you run tasks (build, test, jar); in Maven you run phases (package, verify, install). When something custom is needed, Gradle lets you register your own task in a few lines of Kotlin — the equivalent in Maven is writing or configuring a plugin, which is heavier.

Why Gradle is faster

Three mechanisms, all visible in the output below:

The daemon. Gradle keeps a long-lived background JVM warm between builds, so startup and JIT compilation costs are paid once, not per invocation.
Incremental builds. Gradle fingerprints every task's inputs and outputs. If nothing changed, the task is skipped as UP-TO-DATE — you'll see it in the output in the next section.
Build cache. Task outputs can be shared across branches and machines (with a remote cache), so a task your colleague already ran doesn't run again for you.

Honest framing: on a tiny project like ours the difference is seconds. On a fifty-module monorepo it's the difference between a coffee break and a context switch — which is exactly where Gradle dominates. Maven has no built-in daemon (the third-party mvnd exists but is not standard), and its lifecycle re-runs phases even when nothing changed.

The Gradle wrapper

Same idea as Maven's, and non-negotiable: gradlew / gradlew.bat plus gradle/wrapper/ must be committed. Newer projects get it from gradle init; for an existing one:

gradle wrapper --gradle-version 8.10
./gradlew build   # pinned Gradle, no local install needed

Side by side: the actual terminal output

Same project, both tools. First Maven — notice how the output narrates the lifecycle, plugin by plugin:

$ mvn package
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.acme:hello >----------------------------
[INFO] Building hello 1.0.0
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ hello ---
[INFO] Changes detected - recompiling the module! :source
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO]
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ hello ---
[INFO] Compiling 1 source file with javac [debug release 21] to target/test-classes
[INFO]
[INFO] --- surefire:3.2.2:test (default-test) @ hello ---
[INFO] Running com.acme.AppTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] --- jar:3.3.0:jar (default-jar) @ hello ---
[INFO] Building jar: /home/you/hello/target/hello-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.214 s
[INFO] Finished at: 2026-10-04T14:58:11+05:30
[INFO] ------------------------------------------------------------------------

Now Gradle — terse, task-oriented. Run it twice to see the incremental engine:

$ ./gradlew build

> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes
> Task :compileTestJava
> Task :processTestResources NO-SOURCE
> Task :testClasses
> Task :test
> Task :jar
> Task :assemble
> Task :check
> Task :build

BUILD SUCCESSFUL in 4s
7 actionable tasks: 7 executed

$ ./gradlew build     # nothing changed — watch what happens

> Task :compileJava UP-TO-DATE
> Task :compileTestJava UP-TO-DATE
> Task :test UP-TO-DATE
> Task :jar UP-TO-DATE
> Task :build UP-TO-DATE

BUILD SUCCESSFUL in 892ms
7 actionable tasks: 7 up-to-date

That second run — under a second, everything UP-TO-DATE — is the Gradle experience in miniature. Maven would recompile and re-run the tests on the second invocation (it does have some incremental compilation, but the lifecycle phases themselves always execute).

Maven vs Gradle: the comparison

	Maven	Gradle
Philosophy	Convention over configuration	Your build is code
Build file	`pom.xml` (XML, declarative)	`build.gradle.kts` (Kotlin) or `build.gradle` (Groovy)
Build model	Fixed lifecycle phases; plugins bind goals to phases	Task dependency graph; you can add tasks freely
Learning curve	Shallow for standard projects; steep when you fight conventions	Steeper up front; pays off with custom logic
Speed	Re-runs lifecycle phases; fine for small/medium builds	Daemon + incremental + build cache; wins on large builds
Ecosystem default	Spring Initializr default; most enterprise Java	Android Studio default; large monorepos, Kotlin shops
Dependency conflicts	"Nearest wins" in the dependency tree	Newest version wins by default

p>Decision rule: don't re-litigate a repo's existing choice — both tools build the same jars. For a new project: if your ecosystem has a default (Spring → Maven, Android → Gradle), take the default and move on. If you're building a large multi-module monorepo or need serious build customization, Gradle earns its complexity. Otherwise, Maven's boring predictability is a feature, not a limitation.

Multi-module projects, briefly

Real projects split into modules — an app that depends on a lib, for example. Both tools handle this with one aggregator file. Maven uses a parent POM with <packaging>pom</packaging>:

<!-- parent pom.xml: declares the modules, builds them in dependency order -->
<packaging>pom</packaging>
<modules>
    <module>lib</module>
    <module>app</module>
</modules>

Gradle uses settings.gradle.kts at the root:

// settings.gradle.kts: same idea, one line
include("lib", "app")

In both, the parent/root also holds shared configuration — dependency versions in Maven's <dependencyManagement>, common config in Gradle's root build.gradle.kts — so modules stay consistent. One command (mvn package, ./gradlew build) builds every module in the right order. This matters because trap #1 below gets dramatically worse with modules: each module brings its own transitive dependencies, and the conflict surface multiplies.

When it breaks: 4 build traps

Trap 1 — Two versions of the same library: Maven's "nearest wins"

Symptom: everything compiles, then production throws NoSuchMethodError or ClassNotFoundException for a library method you know exists. Classic cause: your code depends on library A (which pulls in commons-lang3:3.14.0) and library B (which pulls in commons-lang3:3.8.0). Only one version lands on the classpath. Maven's rule is nearest wins: the version closest to your project in the dependency tree is chosen — and "closest" is about tree depth, not newest. So you silently get 3.8.0, whose method signature differs, and the JVM discovers this at runtime.

Diagnose it:

mvn dependency:tree -Dincludes=org.apache.commons:commons-lang3
# Gradle equivalent:
./gradlew dependencies --configuration runtimeClasspath | grep -A3 commons-lang3

Fix: declare the version you actually want once, explicitly, in <dependencyManagement> — it overrides every transitive claim. Or add an <exclusion> to the dependency dragging in the old version. (Gradle's default is the opposite — newest wins — which fails differently: an untested newer version. Either way, the tree command is how you see the truth.)

Trap 2 — SNAPSHOT versions: the moving target

Symptom: "it worked yesterday." A teammate's build passes, yours fails, nobody changed anything — or CI is red on code that was green at lunch. The culprit is often a version ending in -SNAPSHOT, e.g. 1.2.0-SNAPSHOT: Maven treats snapshots as nightly builds that can change at any time, re-checking for updates on a daily schedule. Your build silently picked up someone's half-finished Tuesday code.

Diagnose it: search your POMs and dependency tree for -SNAPSHOT on anything you don't own and actively develop. Fix: depend on released versions for everything cross-team — releases are immutable, so yesterday's build and today's build resolve identically. Keep -SNAPSHOT only for the module you are actively editing. If you must chase a fresh snapshot right now, mvn -U package forces an immediate update check instead of waiting for the daily one.

Trap 3 — The wrapper that never got committed

Symptom: "works on my machine" — the build passes locally and fails in CI (or vice versa), with errors about unrecognized plugin versions or lifecycle behavior. The cause: the developer ran a locally installed mvn or gradle, and CI has a different version. Build tools are not perfectly backward compatible; a 3.8-vs-3.9 or 7-vs-8 gap produces exactly these ghosts.

Diagnose it: does the repo root contain mvnw (plus .mvn/wrapper/) or gradlew (plus gradle/wrapper/)? If not, that's the bug. Fix: generate and commit it — mvn wrapper:wrapper for Maven, gradle wrapper for Gradle — and make the README and CI scripts invoke ./mvnw / ./gradlew, never a bare mvn / gradle. The wrapper pins the exact tool version in version control, so every machine builds with the same one.

Trap 4 — Wrong dependency scope: test libraries leaking into production

Symptom (the common direction): your shipped jar is bloated, or a security scan flags JUnit inside your production artifact — because someone declared the test dependency without <scope>test</scope> (Maven) or used implementation instead of testImplementation (Gradle). The reverse direction bites too: mark something test-scoped that your main code actually uses, and compilation fails with "package does not exist" — confusing, because the dependency is right there in the file.

Diagnose it: mvn dependency:list shows each dependency's scope; and check the artifact itself — jar tf target/hello-1.0.0.jar | grep -i junit should print nothing. Fix: audit scopes when you add a dependency — ask "does production code need this at runtime?" If yes, default scope; if only tests need it, test / testImplementation; if the container provides it (like the servlet API on a server), Maven's provided. Wrong scope is a one-line mistake with production-sized consequences.

What's next

You can now read any Java repo's build file: the GAV coordinates that identify the project, the dependencies it pulls in, the lifecycle or task graph a single command triggers, and the wrapper that makes it reproducible. You also know the four failure modes that waste the most build-debugging hours — nearest-wins conflicts, SNAPSHOT drift, missing wrappers, and scope leaks — and the exact commands that diagnose each one.

The build compiles your code and runs your tests — so the natural next step is writing tests worth running. That's the next post in this track, "JUnit 5 & Mockito: Testing That Catches Bugs" (plain-English, runnable, no prior testing-framework experience assumed). After that, "CI/CD with GitHub Actions for Java Projects" puts ./mvnw verify behind an automated gate so the traps above get caught by a machine, not by you at midnight.

Field check before you move on: scaffold the hello project from this post — the pom.xml, App.java, and AppTest.java above — and run mvn package (or the Gradle equivalent) until you see BUILD SUCCESS. Then deliberately break one thing: change JUnit's scope, or add a -SNAPSHOT dependency, and watch the failure. Fixing a build you broke on purpose is the fastest way to make the traps section stick.

Continue: Java Learning Roadmap 2026

Search This Blog

JavaMakeUse: Learn Java, Python, AI, Cloud & More