Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 41 ยท Alternatives and Migration

Maven vs Gradle

Compare Maven and Gradle: declarative XML versus scripted builds, speed, ecosystem, when to pick each, and how a pom.xml maps to a build.gradle file.

Maven and Gradle solve the same problem: turn source code and a list of libraries into tested, packaged software. They disagree about how you describe that. Maven asks you to declare what the project is and then follows a fixed lifecycle. Gradle asks you to program a graph of tasks, with sensible defaults supplied by plugins.

Neither is "the right one". Both are mature, both resolve from the same Maven Central, and a library built by one is usable from the other. This lesson compares them honestly, shows the same project in both, and explains how to move from one to the other. Gradle cannot run on this site, so its files are read-only; the TryIts model the ideas in Java.

Two philosophies

Maven Declare the project. A fixed lifecycle does the rest.
Gradle Script a task graph. Plugins add the defaults.

Same repositories, same artifacts, different build language.

1 / 2

Declarative versus scripted

A pom.xml is data. It says what the project is called, which Java release it targets and which libraries it needs. There are no loops or if statements in it. When you want behavior beyond the defaults you configure a plugin, and when no plugin exists you write one (see Writing a Simple Maven Plugin). The payoff is that every Maven project exposes the same phases and the same commands: if you can build one, you can build a thousand.

A build.gradle (Groovy) or build.gradle.kts (Kotlin) file is a program. You can read environment variables, loop over modules, define a new task in four lines and make it depend on another. That freedom is why Gradle dominates Android and large polyglot builds. The cost is that two Gradle builds can be organized very differently, and a clever script is harder to read than a plain list of dependencies.

Here is the same small library in both tools. The Maven version first:

XML
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>textkit</artifactId>
  <version>1.0.0</version>

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

  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>33.4.0-jre</version>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.11.4</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

And the Gradle version in the Kotlin DSL:

Kotlin
plugins {
    `java-library`
}

group = "com.example"
version = "1.0.0"

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

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.google.guava:guava:33.4.0-jre")
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
}

tasks.test {
    useJUnitPlatform()
}

Notice what the Gradle file needs that the POM does not: the repositories block (Maven's super POM already points at Central), and useJUnitPlatform() (Surefire detects JUnit by itself). Notice what the POM needs that Gradle does not: modelVersion, and a full XML tag for every coordinate part.

The dependency vocabulary

Gradle's configurations roughly correspond to Maven's scopes. The match is not exact, because Gradle separates the compile classpath of your code from the compile classpath of consumers, and Maven does not.

Maven scope Gradle configuration Meaning
compile implementation (or api in java-library) Needed to compile and run
provided compileOnly Needed to compile, supplied at run time
runtime runtimeOnly Not needed to compile, needed to run
test testImplementation Only for tests

The api versus implementation split is a real feature: a library can keep its internal dependencies off its consumers' compile classpath. Maven can only approximate this with careful use of the scopes described in Dependency Scopes.

One task graph, two descriptions

Underneath, both tools run a directed graph of steps. Maven's graph is a straight line of phases (validate, compile, test, package), where each step implicitly follows the previous one, as covered in Lifecycles and Phases. Gradle's graph is a real DAG: build depends on test and jar, both of which depend on classes, which depends on compileJava and processResources.

The first TryIt is a stand-in that parses a dependency list from a POM fragment and from a Gradle fragment, maps both to Maven-style scopes and confirms that they describe the same project. The real Gradle parser is, of course, a full Groovy or Kotlin compiler; this one only understands the single-quoted shorthand.

Java Same dependencies, two syntaxes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Speed and incremental work

Gradle's headline advantage is that it avoids work. Each task records a fingerprint of its inputs and outputs; if nothing changed since the last run, the task is reported as UP-TO-DATE and skipped. A daemon keeps the JVM warm, a build cache can reuse outputs from earlier builds or other machines, and an optional configuration cache skips even the setup phase.

Maven has traditionally re-run every phase of the requested lifecycle each time. Individual plugins are smart: the compiler plugin detects "nothing to compile", and Surefire reruns tests unless you skip them. But the engine itself does not skip phases. The gap has narrowed: the Maven Daemon (mvnd), parallel builds with -T and the Maven build cache extension all attack the same problem (see Maven in CI and Faster Builds). For a mid-sized project, a clean CI build is similar in both tools; the difference shows up in the edit-compile-test loop on large multi-module codebases.

The second TryIt models fingerprints. The graph is Gradle's, and it runs three times: twice with identical sources, then after a source change. Watch which tasks are skipped.

Java Why Gradle can skip tasks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The real Gradle fingerprints file contents and compiler output, and it can tell that a comment-only change leaves the compiled classes untouched. The principle, however, is the one shown here: a task re-runs only if its inputs, or the outputs of tasks it depends on, changed.

Ecosystem and tooling

Maven's ecosystem is enormous and stable. Nearly every Java library documents its Maven coordinates first, and almost every IDE, CI service and static-analysis tool speaks pom.xml natively. Spring Boot, Jakarta EE and Quarkus all support both tools equally well.

Gradle has a plugin portal of its own and is the default for Android, Kotlin Multiplatform and many large open-source projects. Its Kotlin DSL gives you auto-completion inside the build file, which Maven's XML can only match through schema support.

Which should you choose?

Prefer Maven when you want conventions that every contributor already knows, when the build is mostly "compile, test, package, publish", or when your team values being able to read any project's build in a minute. Prefer Gradle when build time dominates your day, when you need custom tasks or several languages in one build, or when you build for Android.

Do not migrate for fashion. A migration costs weeks on a large project, and the usual reasons that justify it are measured build times, not preference. If your complaint is speed, try -T, mvnd and caching first.

Migrating a POM to Gradle

If you do move, gradle init run in a directory that contains a pom.xml offers to convert the project. It reads the POM, creates settings.gradle(.kts) with the modules and generates a build file per module. Treat the result as a first draft and check these points by hand.

  1. Dependencies and scopes. Review each mapping from the table above, especially provided and optional dependencies.
  2. BOMs. An imported BOM in dependencyManagement becomes implementation(platform("group:artifact:version")).
  3. Plugins. Each Maven plugin needs a Gradle counterpart (JaCoCo, Checkstyle, shade, publishing). Custom plugins have to be rewritten.
  4. Resource filtering and profiles. There is no direct equivalent: filtering becomes processResources { expand(...) }, and profiles become project properties or separate source sets.
  5. Publishing. Use the maven-publish plugin and keep the same groupId:artifactId:version, so consumers do not notice the change.

Verify the migration by comparing the produced JARs and the resolved dependency lists before you delete the POM.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the biggest difference in how Maven and Gradle describe a build?

    Maven declares the project and runs a fixed lifecycle. Gradle builds a graph of tasks that can be scripted. Both use the same repositories and artifact format.
  2. 2. Which Gradle configuration corresponds most closely to Maven's test scope?

    testImplementation puts a library on the test compile and run classpaths only, exactly like the test scope.
  3. 3. A Gradle task is reported as UP-TO-DATE. What does that mean?

    Gradle fingerprints task inputs and outputs and skips a task when nothing relevant changed since the last successful run.
  4. 4. Your Maven build is slow in CI. What is a reasonable first step before migrating to Gradle?

    Parallelism, cache reuse and the Maven daemon often close most of the gap, at a fraction of the cost of a full migration.

Summary

  • Maven is declarative with a fixed lifecycle; Gradle is scripted with a task graph.
  • Both resolve from Maven Central and publish the same artifact format, so they interoperate.
  • Maven scopes map to Gradle configurations (compile to implementation, test to testImplementation), with api as a Gradle-only extra.
  • Gradle's speed comes from skipping up-to-date tasks, daemons and caches; Maven has -T, mvnd and a build cache extension.
  • gradle init can convert a POM, but the result needs a manual review. The Gradle files here were not run, and the Java models above are stand-ins.

Next, learn to read the errors you will meet in either tool: Troubleshooting Common Maven Errors.