Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Performance and Migration

Migrating from Maven or Ant to Gradle

A practical guide to migrating from Maven or Ant to Gradle: gradle init, mapping POM elements, scope to configuration table, plugins, profiles, multi-module builds and validation.

Many teams arrive at Gradle with a working Maven (or older Ant) build. Rewriting it from scratch is risky; a careful migration keeps the same artifacts while gaining Gradle's speed and flexibility. The good news is that the concepts map closely: a Maven module is a Gradle project, a POM dependency is a Gradle dependency, a Maven plugin is often a Gradle plugin.

This lesson gives a step-by-step plan, the mapping tables you need, and how to verify the result. It assumes you know the Java plugins and multi-project builds.

Gradle and Maven cannot run on this site. Commands and build files are read-only. A Java stand-in converts Maven scopes to Gradle configurations and runs on Piston.

Step 1: let gradle init do the first pass

In the Maven project's root run:

TEXT
gradle init

If Gradle finds a pom.xml, it offers to convert the Maven build. It reads the POM (and modules), then generates settings.gradle(.kts), one build script per module, a gradle.properties and the wrapper. Choose the Kotlin DSL for new work. The result is a starting point, not a finished migration; review the files carefully.

Immediately add the wrapper if it is missing: gradle wrapper --gradle-version <version>. Commit gradlew, gradlew.bat and gradle/wrapper/.

Step 2: map the POM

Maven (pom.xml) Gradle (build.gradle.kts)
<groupId>, <version> group = "...", version = "..."
<artifactId> rootProject.name or archive base name
<packaging>jar</packaging> java / java-library plugin
<packaging>war</packaging> war plugin
<modules> include(...) in settings.gradle.kts
<parent> convention plugin or root configuration
<properties> gradle.properties, val, version catalog
<dependencyManagement> platform(...), constraints, catalog
<repositories> repositories { }
<build><sourceDirectory> sourceSets.main { java.srcDirs(...) }
maven.compiler.release java { toolchain { ... } } or options.release = 21

Step 3: map the dependency scopes

Maven scope Gradle configuration
compile (library) api (if exposed) or implementation
provided compileOnly (plus testImplementation if tests need it)
runtime runtimeOnly
test testImplementation
import (BOM) implementation(platform(...))
system avoid; use a local repository or files(...)

Example:

XML
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>2.0.16</version>
</dependency>
<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>5.11.4</version>
  <scope>test</scope>
</dependency>

becomes

Kotlin
dependencies {
    implementation("org.slf4j:slf4j-api:2.0.16")
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
}
Java Stand-in: converting Maven scopes to Gradle configurations

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.

Step 4: map the plugins

Maven plugin Gradle equivalent
maven-compiler-plugin java plugin, JavaCompile options
maven-surefire-plugin test task
maven-failsafe-plugin JVM test suite integrationTest
maven-jar-plugin jar task and manifest
maven-shade-plugin Shadow plugin
maven-source-plugin, maven-javadoc-plugin withSourcesJar(), withJavadocJar()
maven-deploy-plugin, maven-gpg-plugin maven-publish, signing
jacoco-maven-plugin jacoco plugin
spring-boot-maven-plugin org.springframework.boot plugin
exec-maven-plugin Exec task or application plugin
maven-resources-plugin filtering processResources { expand(...) }
maven-enforcer-plugin dependency constraints, failOnVersionConflict()

Resource filtering example: Maven replaces ${project.version} in resources. In Gradle:

Kotlin
tasks.processResources {
    filesMatching("application.properties") {
        expand("version" to project.version)
    }
}

and the file uses ${version}.

Step 5: profiles and lifecycle

  • Profiles (-Pprod) become Gradle properties and conditionals: if (project.hasProperty("prod")) { ... }, or separate tasks and source sets. Prefer explicit tasks over big conditionals.
  • Lifecycle phases differ: Maven's clean install roughly maps to ./gradlew clean build publishToMavenLocal. Maven verify is ./gradlew check; package is assemble.
  • Multi-module reactor becomes a multi-project build; mvn -pl app -am is ./gradlew :app:build (dependencies are built automatically).

Migrating from Ant

Ant build files consist of targets and tasks with no dependency management. Gradle can import them as is:

Kotlin
ant.importBuild("build.xml") { antTargetName -> "ant-$antTargetName" }

Each Ant target becomes a Gradle task (prefixed in this example). This lets you migrate target by target: wrap the old ones, replace them with native tasks over time, and replace lib/*.jar with real dependencies from a repository.

Step 6: verify the migration

  1. Build both ways and compare the artifacts: file lists (unzip -l), manifest, and dependency lists (mvn dependency:tree versus ./gradlew dependencies). Expect small differences in transitive versions; Gradle chooses the highest version by default, Maven the nearest.
  2. Run the full test suite on both and compare counts.
  3. Check generated POMs of published artifacts.
  4. Update CI scripts, Dockerfiles, IDE settings and documentation.
  5. Remove pom.xml files only after the team has used the new build for a while.

Common pitfalls

  • Version conflict resolution differs. Use dependencyInsight to see why a version was picked, and constraints to pin one.
  • Missing provided dependencies in tests. Add testImplementation as well.
  • Properties with ${...} in resources are no longer filtered until you configure processResources.
  • Hard-coded target/ paths in scripts: Gradle writes to build/.
  • Snapshot repositories must be declared again.
Java Stand-in: nearest wins (Maven) vs highest wins (Gradle)

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does gradle init do in a directory that contains a pom.xml?

    gradle init detects a Maven build and generates settings and build scripts from the POM and its modules.
  2. 2. Which Gradle configuration corresponds to Maven's provided scope?

    provided means available at compile time but supplied by the runtime environment, which is compileOnly.
  3. 3. Which task roughly replaces mvn verify?

    check runs tests and other verification, like Maven's verify phase.
  4. 4. How do conflicting versions of the same library resolve by default in Gradle?

    Gradle picks the highest requested version, unlike Maven's nearest-definition rule.

Summary

  • Start with gradle init, then review and clean up what it generates.
  • Map POM elements, scopes (compile to api/implementation, provided to compileOnly) and plugins by table.
  • Replace profiles with properties and tasks; replace resource filtering with processResources.
  • Import Ant builds with ant.importBuild and migrate target by target.
  • Verify by comparing artifacts, dependency trees and test counts; remember the version conflict rule differs.

Next: Groovy to Kotlin DSL and upgrading Gradle