Gradle in Java

Su Suriya Ravichandran Updated 18 Nov 2026
10 min read ·Lesson 262 of 306

Gradle is a build tool that compiles, tests, packages and runs Java projects. Instead of an XML file, Gradle in Java projects describe the build in a short script written in Kotlin or Groovy, and Gradle skips any step whose inputs have not changed, which keeps builds fast.

This lesson installs Gradle, creates a project with gradle init, explains the Gradle Wrapper and every line of build.gradle.kts, runs the most common tasks, and compares the Kotlin and Groovy DSLs. It ends with a grade calculator built and tested with Gradle. If you already know Maven, see Maven in Java for the same ideas in Maven terms.


Gradle vs Maven for Java Projects

Both tools use the same folder layout and download libraries from Maven Central, so a Java developer can switch between them easily.

FeatureMavenGradle
Build filepom.xml (XML)build.gradle.kts (Kotlin) or build.gradle (Groovy)
Unit of workPlugin goals bound to lifecycle phasesTasks that depend on other tasks
Source folderssrc/main/java, src/test/javaSame
Output foldertarget/build/
Skips unchanged workPartlyYes, task by task (up-to-date checks and build cache)
Pinned tool versionMaven Wrapper (mvnw)Gradle Wrapper (gradlew)
Version conflictsNearest declaration winsHighest version wins
my-app/
├── settings.gradle.kts     <- project name, list of subprojects
├── build.gradle.kts        <- plugins, dependencies, Java version
├── gradlew / gradlew.bat   <- Gradle Wrapper scripts
├── gradle/wrapper/         <- wrapper JAR and properties
└── src/
    ├── main/java/...
    └── test/java/...

How it works:

  • settings.gradle.kts is read first. It names the project and, in larger builds, lists the subprojects.
  • build.gradle.kts describes how to build one project. Plugins add tasks such as compileJava, test and jar.
  • Gradle writes everything it produces under build/, which you add to .gitignore just like Maven's target/.

Install Gradle and Check the Version

Gradle runs on the JVM, and Gradle 9 needs Java 17 or newer to run. Install it with a package manager such as SDKMAN! (sdk install gradle), Homebrew (brew install gradle) or Scoop (scoop install gradle), or download it from gradle.org.

gradle --version

Output (shortened):

------------------------------------------------------------
Gradle 9.9.0
------------------------------------------------------------

Launcher JVM:  25.0.1 (Eclipse Adoptium 25.0.1+8-LTS)
OS:            Linux 6.8.0 amd64

How it works:

  • Launcher JVM is the Java that runs Gradle itself. It is not necessarily the Java your code is compiled for; that is set by the toolchain shown later.
  • You only need an installed Gradle to create a project. After that, every developer uses the project's wrapper, so their installed version does not matter.

Note: Gradle 9.9.0 was released in November 2026. Any recent 9.x version works for every example in this lesson.


Create a Gradle Project With gradle init

gradle init generates a ready-to-run project. The options below create a Java application with JUnit tests and the Kotlin DSL, without asking questions.

mkdir greeter && cd greeter
gradle init --type java-application --dsl kotlin --test-framework junit-jupiter \
  --package com.gocourse.greeter --project-name greeter --java-version 25 \
  --no-split-project --no-incubating

On Windows Command Prompt, write the command on one line without the `` characters.

Output (shortened):

> Task :init
Learn more about Gradle by exploring our Samples at https://docs.gradle.org/9.9.0/samples/sample_building_java_applications.html

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

The main generated files:

greeter/
├── settings.gradle.kts
├── gradle/libs.versions.toml           <- version catalog
├── gradlew, gradlew.bat, gradle/wrapper/
└── app/
    ├── build.gradle.kts
    └── src/
        ├── main/java/com/gocourse/greeter/App.java
        └── test/java/com/gocourse/greeter/AppTest.java

Run the app through the wrapper:

./gradlew run

Output:

> Task :app:run
Hello World!

BUILD SUCCESSFUL in 3s
2 actionable tasks: 2 executed

How it works:

  • --type java-application applies the application plugin, which adds the run task. The code lives in a subproject called app, so the task path is :app:run.
  • gradle/libs.versions.toml is a version catalog: one file that names every library and its version. Gradle Dependencies explains it in detail.
  • On Windows, run gradlew run (or .\gradlew run in PowerShell) instead of ./gradlew run.

The Gradle Wrapper Explained

The Gradle Wrapper is a small script plus a properties file committed with the project. It downloads the exact Gradle version the project needs, so every developer and CI server builds with the same version.

# gradle/wrapper/gradle-wrapper.properties
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-9.9.0-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
./gradlew --version

Output (shortened):

Gradle 9.9.0

Add the wrapper to a project that does not have one, or upgrade it:

gradle wrapper --gradle-version 9.9.0

How it works:

  • The first ./gradlew call downloads the distribution from distributionUrl into ~/.gradle/wrapper/dists. Later calls reuse it.
  • Commit gradlew, gradlew.bat and the whole gradle/wrapper folder. Never commit build/ or .gradle/.
  • On Linux and macOS, if you see Permission denied, make the script executable with chmod +x gradlew.

build.gradle.kts Explained Line by Line

You can also write a Gradle project by hand. This single-project build has no app subfolder, so the files sit next to src/.

// settings.gradle.kts
rootProject.name = "hello-gradle"
// build.gradle.kts
plugins {
    application                         // adds java + run + distribution tasks
}

group = "com.gocourse"
version = "1.0.0"

repositories {
    mavenCentral()                      // where libraries are downloaded from
}

dependencies {
    testImplementation(platform("org.junit:junit-bom:6.1.3"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)   // compile and run with Java 25
    }
}

application {
    mainClass = "com.gocourse.hello.HelloGradle"
}

tasks.test {
    useJUnitPlatform()                  // run tests with JUnit 6
}
// src/main/java/com/gocourse/hello/HelloGradle.java
package com.gocourse.hello;

public class HelloGradle {
    public static void main(String[] args) {
        System.out.println("Built by Gradle, running on Java " + Runtime.version().feature());
    }
}
gradle wrapper --gradle-version 9.9.0
./gradlew run

Output:

> Task :run
Built by Gradle, running on Java 25

BUILD SUCCESSFUL in 2s
2 actionable tasks: 2 executed

How it works:

BlockPurpose
pluginsApplies plugins. application includes the java plugin and adds run
group, versionProject coordinates, also used in the JAR name
repositoriesWhere to look for dependencies
dependenciesLibraries, each added to a configuration such as implementation
java.toolchainThe Java version used to compile, test and run
application.mainClassThe class run starts
tasks.testConfigures the existing test task
  • The toolchain decouples your code's Java version from the JDK that runs Gradle. Gradle looks for an installed JDK 25 and fails with a clear message if it cannot find one.
  • Since Gradle 9, JUnit Platform projects declare junit-platform-launcher as testRuntimeOnly themselves; Gradle no longer adds it automatically.

Run Gradle Tasks From the Command Line

A task is one unit of work, such as compiling or running tests. List the tasks a project offers:

./gradlew tasks

Output (shortened):

Application tasks
-----------------
run - Runs this project as a JVM application

Build tasks
-----------
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.
clean - Deletes the build directory.
jar - Assembles a jar archive containing the main classes.

Verification tasks
------------------
check - Runs all checks.
test - Runs the test suite.
CommandWhat it does
./gradlew buildCompiles, tests and creates the JAR
./gradlew testCompiles and runs the tests
./gradlew runRuns mainClass
./gradlew run --args="a b"Runs it with arguments
./gradlew cleanDeletes build/
./gradlew build -x testBuilds but skips the test task
./gradlew build --scanUploads a detailed build report (asks for permission)

Run build twice in a row:

./gradlew build
./gradlew build

Output of the second run:

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

How it works:

  • Gradle records each task's inputs and outputs. If nothing changed, the task is up-to-date and skipped, which is why the second build takes under a second.
  • -x test excludes one task. Use it sparingly; tests exist to stop broken code from being packaged.
  • Gradle keeps a background daemon running after the first build, so later builds start faster. Stop it with ./gradlew --stop.

Kotlin DSL vs Groovy DSL in Gradle

Gradle supports two script languages. New projects default to the Kotlin DSL, but many older projects use Groovy.

Kotlin DSLGroovy DSL
File namesbuild.gradle.kts, settings.gradle.ktsbuild.gradle, settings.gradle
StringsDouble quotes onlySingle or double quotes
Method callsAlways use parenthesesParentheses optional
IDE supportFull code completion and type checkingWeaker completion

The same build in Groovy:

// build.gradle
plugins {
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation platform('org.junit:junit-bom:6.1.3')
    testImplementation 'org.junit.jupiter:junit-jupiter'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

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

application {
    mainClass = 'com.gocourse.hello.HelloGradle'
}

tasks.named('test') {
    useJUnitPlatform()
}

How it works:

  • Both files produce exactly the same build; only the syntax differs.
  • The Kotlin DSL is checked as you type, so a misspelled block name shows an error in the IDE instead of at build time. The rest of this tutorial uses it.

Real-World Example: Gradle in Java for a Grade Calculator

This project turns command-line arguments like Asha:92 into letter grades and a class average. It shows a complete hand-written Gradle build with the toolchain, the application plugin and JUnit tests.

// settings.gradle.kts
rootProject.name = "grade-calculator"
// build.gradle.kts
plugins {
    application
}

group = "com.gocourse"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    testImplementation(platform("org.junit:junit-bom:6.1.3"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

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

application {
    mainClass = "com.gocourse.grades.GradeApp"
}

tasks.test {
    useJUnitPlatform()
    testLogging {
        events("passed", "failed")       // print each test result
    }
}
// src/main/java/com/gocourse/grades/GradeCalculator.java
package com.gocourse.grades;

import java.util.List;

public class GradeCalculator {

    /** Converts marks out of 100 into a letter grade. */
    public static char letterFor(int marks) {
        if (marks < 0 || marks > 100) {
            throw new IllegalArgumentException("Marks must be 0-100, got " + marks);
        }
        if (marks >= 90) return 'A';
        if (marks >= 75) return 'B';
        if (marks >= 60) return 'C';
        if (marks >= 40) return 'D';
        return 'F';
    }

    public static double average(List<Integer> allMarks) {
        return allMarks.stream().mapToInt(Integer::intValue).average().orElse(0);
    }
}
// src/main/java/com/gocourse/grades/GradeApp.java
package com.gocourse.grades;

import java.util.ArrayList;
import java.util.List;

public class GradeApp {
    public static void main(String[] args) {
        if (args.length == 0) {
            System.out.println("Usage: gradlew run --args=\"Name:marks Name:marks\"");
            return;
        }
        List<Integer> allMarks = new ArrayList<>();
        for (String entry : args) {
            String[] parts = entry.split(":");
            String name = parts[0];
            int marks = Integer.parseInt(parts[1]);
            allMarks.add(marks);
            System.out.printf("%-6s %3d  %c%n", name, marks, GradeCalculator.letterFor(marks));
        }
        System.out.printf("Class average: %.1f%n", GradeCalculator.average(allMarks));
    }
}
// src/test/java/com/gocourse/grades/GradeCalculatorTest.java
package com.gocourse.grades;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;

import java.util.List;
import org.junit.jupiter.api.Test;

class GradeCalculatorTest {

    @Test
    void boundaryMarksGetTheHigherGrade() {
        assertEquals('A', GradeCalculator.letterFor(90));
        assertEquals('B', GradeCalculator.letterFor(75));
        assertEquals('F', GradeCalculator.letterFor(39));
    }

    @Test
    void marksOutsideRangeAreRejected() {
        assertThrows(IllegalArgumentException.class, () -> GradeCalculator.letterFor(101));
    }

    @Test
    void averageOfThreeStudents() {
        assertEquals(75.0, GradeCalculator.average(List.of(92, 78, 55)));
    }
}

Build, test and run:

gradle wrapper --gradle-version 9.9.0
./gradlew build
./gradlew run --args="Asha:92 Ravi:78 Meena:55"

Output:

> Task :test

GradeCalculatorTest > boundaryMarksGetTheHigherGrade() PASSED

GradeCalculatorTest > marksOutsideRangeAreRejected() PASSED

GradeCalculatorTest > averageOfThreeStudents() PASSED

BUILD SUCCESSFUL in 5s
7 actionable tasks: 7 executed

> Task :run
Asha    92  A
Ravi    78  B
Meena   55  D
Class average: 75.0

BUILD SUCCESSFUL in 1s
2 actionable tasks: 1 executed, 1 up-to-date

How it works:

  1. Two small files. settings.gradle.kts names the project and build.gradle.kts holds the whole build. Gradle's conventions supply the source folders, output folders and task order.
  2. Toolchain. Both the compile and the run task use Java 25, even if Gradle itself was started with a different JDK.
  3. Tests run in build. build depends on check, which depends on test. testLogging prints each result, and a failure stops the build. The HTML report is in build/reports/tests/test/index.html.
  4. Up-to-date checks. In the run step, compileJava was already up-to-date from build, so Gradle executed only run itself.
  5. Output files. The JAR is build/libs/grade-calculator-1.0.0.jar, named from rootProject.name and version.

The next lesson, Gradle Build, looks inside the build: the task graph, custom tasks and multi-project builds. To compare this with the same app built by Maven's plugins, see Maven Plugins.

0 Comments

Reviewed before they appear

No comments yet.

Java
Java Introduction Java Features Java Syntax Java Comments Java Statements Java Output Java Variables Java Data Types Java Type Casting Java Operators Java Strings Java Numbers Java Math Java Booleans Java User Input Java Conditions Java If Else Java Switch Java While Loop Java For Loop Java Break Java Continue Java Arrays Java Methods Java Parameters Java Return Values Java Scope Java Recursion Install Java Install JDK Java IDEs Java JDK Java JRE Java JVM Java Compiler Java File Compile Java Run Java JShell Basics Java Packages Java OOP Java Classes Java Objects Class Methods Constructors Constructor Overload this Keyword static Keyword final Keyword Encapsulation Inheritance Polymorphism Abstraction Access Modifiers super Keyword Method Overload Method Override Instanceof Operator Nested Classes Inner Classes Anonymous Classes Enums Records Array Basics Array Length Loop Arrays Multidimensional Arrays Array Copy Array Sorting Array Search ArrayList LinkedList HashSet TreeSet HashMap TreeMap Queue Interface Deque Interface Stack Class Iterator List Interface Set Interface Map Interface Collections Class Comparable Comparator Generics Basics Generic Classes Generic Methods Wildcards String Basics String Length String Methods String Concatenation String Compare String Search String Replace String Split String Format StringBuilder StringBuffer Text Blocks Regular Expressions Number Types Integer Class Float Class Double Class BigInteger BigDecimal Math Class Random Numbers Number Format Date Basics LocalDate LocalTime LocalDateTime ZonedDateTime Date Formatting Date Parsing Period Class Duration Class Java Instant Class Java Exception Basics Java try...catch Java Multiple Catch Blocks Java finally Block Java throw Keyword Java throws Keyword Java Checked Exceptions Java Unchecked Exceptions Java Custom Exceptions Java try-with-resources Java Exception Chaining Java File Basics Java Create Files Java Read Files Java Write Files Java Delete Files Java File Paths Java File Class Java BufferedReader Java BufferedWriter Java FileInputStream Java FileOutputStream Java Object Streams Java Directory Handling Java NIO Basics Java Files API Java Input Java Scanner Class Java Console Input Java PrintStream Java InputStream Java OutputStream Java Reader Class Java Writer Class Java Buffered Streams Java Data Streams Java Generics Introduction Java Generic Types Java Generic Methods Java Bounded Types Java Wildcards Java Type Erasure Java Generic Interfaces Java Generic Collections Java Lambda Basics Java Lambda Syntax Java Functional Interfaces Java Method References Java Stream API Java Stream Creation Java Stream Filter Java Stream Map Java Stream Reduce Java Stream Sort Java Stream Collect Java Collectors Class Java Optional Class Java Parallel Streams Java Threads: Thread Basics Create a Thread in Java Java Thread Class Java Runnable Interface Java Thread States Java Thread Sleep Java Thread Join Java Thread Priority Java Synchronization Java Thread Safety Java Race Conditions Java Deadlocks Java Executor Service Java Thread Pools Java Callable Interface Java Future Interface Java CompletableFuture Java Concurrent Collections Java Atomic Classes Java Virtual Threads Java Networking Basics Java URL Class Java URI Class Java HttpClient Java HTTP Requests Java HTTP Responses Java Socket Basics Java ServerSocket Java DatagramSocket Java WebSocket Basics Java JDBC Basics Java JDBC Setup Java Database Connection Java JDBC Connection Interface Java JDBC Statement Java PreparedStatement Java ResultSet Java JDBC CRUD Operations Java JDBC Transactions Java JDBC Batch Update Java Connection Pooling with HikariCP Java JPA Basics: Entities, EntityManager and JPQL Java Hibernate Basics: SessionFactory, Session and HQL Package in Java: Basics Explained with Examples Create Package in Java: Step-by-Step Guide with Examples Import Package in Java: The import Statement Explained Access Control in Java: Packages, Classes and Members JAR File in Java: Create, Run and Inspect JAR Files Java Modules: Introduction to the Java Module System module-info in Java: Every Module Directive Explained Java Module Path: How --module-path Finds Your Modules Java Classpath: How -cp and CLASSPATH Find Your Classes Java Annotations: Basics of @ Metadata in Java Java Built-in Annotations: @Override, @Deprecated and More Java Custom Annotations: Create Your Own @interface Java Annotation Targets: @Target and ElementType Explained Java Reflection API: Inspect and Use Classes at Runtime Java Class Metadata: Names, Modifiers, Hierarchy and Generic Java Dynamic Objects: Create Objects Dynamically With Reflec Java Dynamic Proxy: Intercept Method Calls With Proxy and In Java Security Java Secure Coding Java Password Hashing Java Input Validation Java Cryptography Basics Java KeyStore Basics Java TLS Basics Java SecureRandom Java JUnit Basics Java JUnit Test Methods JUnit Assertions JUnit Test Fixtures JUnit Parameterized Tests Mockito in Java Java Mock Objects Java Integration Testing Java Code Coverage Maven in Java Create a Maven Project in Java Maven Dependencies Maven Plugins Gradle in Java Gradle Build Gradle Dependencies Build Executable JAR in Java Build WAR File in Java HTTP Basics in Java Java Servlet Basics Servlet Lifecycle in Java HttpServletRequest in Java HttpServletResponse in Java JSP in Java JSTL in JSP REST API in Java JSON in Java Java Web Application Spring Framework Basics Spring Boot Tutorial Spring MVC Spring Data JPA Spring Security Spring Boot REST API Jakarta EE Basics Java Deployment JAR Deployment Java WAR Deployment Run Java as a Service Docker Java: Dockerize a Java Application Java Environment Variables and Configuration Java Logging Basics Java Production Setup Java JVM Options Java JVM Monitoring Java Hello World App Java Calculator App Java Number Guess Game Java Student Manager Java Library System Java Bank App Java Todo App Java File Manager Java Quiz App Java REST API Project Java Chat Server Java Employee Manager Java E-commerce API
Ask about this post
AI Ask about this post

Ask questions about Gradle in Java and get answers drawn from it.

Signed-in readers only.