Gradle Dependencies
Gradle dependencies are the libraries your Java project needs, such as Gson for JSON or JUnit for tests. You declare them in build.gradle.kts, and Gradle downloads them, along with the libraries they depend on, and puts each one on the right classpath.
This lesson shows how to add Gradle dependencies, pick the right configuration (implementation, api, runtimeOnly and others), read the dependency tree, understand how Gradle resolves version conflicts, exclude unwanted libraries, use BOMs and constraints, and keep every version in a version catalog. It ends with a student exporter that mirrors the Maven example from Maven Dependencies. If Gradle is new to you, read Gradle in Java first.
Add a Dependency in build.gradle.kts
A dependency is written as "group:name:version", the same coordinates Maven uses. Add it to a configuration, usually implementation.
// build.gradle.kts
plugins {
application
}
repositories {
mavenCentral()
}
dependencies {
implementation("com.google.code.gson:gson:2.13.2")
}
java {
toolchain { languageVersion = JavaLanguageVersion.of(25) }
}
application {
mainClass = "com.gocourse.catalog.CourseJson"
}
package com.gocourse.catalog;
import com.google.gson.Gson;
public class CourseJson {
record Course(String code, String title, int seats) {}
public static void main(String[] args) {
Gson gson = new Gson();
Course course = new Course("JAVA101", "Java Basics", 40);
String json = gson.toJson(course); // object -> JSON
Course copy = gson.fromJson(json, Course.class); // JSON -> object
System.out.println(json);
System.out.println("Same course after round trip: " + copy.equals(course));
}
}
./gradlew run -q
Output:
{"code":"JAVA101","title":"Java Basics","seats":40}
Same course after round trip: true
How it works:
repositories { mavenCentral() }tells Gradle where to find the library. Without a repository, resolution fails withCannot resolve external dependency ... because no repositories are defined.- Downloaded files are cached in
~/.gradle/caches, so the next build works offline. implementationputs Gson on the compile classpath and the runtime classpath of the main code.
Gradle Dependency Configurations Explained
A configuration decides where a dependency is visible. This table also shows the closest Maven scope.
| Configuration | Compile main | Run main | Compile/run tests | Maven scope |
|---|---|---|---|---|
implementation | Yes | Yes | Yes | compile |
api (needs java-library) | Yes, and exposed to consumers | Yes | Yes | compile |
compileOnly | Yes | No | Compile only | provided |
runtimeOnly | No | Yes | Run only | runtime |
testImplementation | No | No | Yes | test |
testRuntimeOnly | No | No | Run only | test |
annotationProcessor | Runs during compile only | No | No | (compiler plugin path) |
dependencies {
implementation("com.google.code.gson:gson:2.13.2") // code imports it
compileOnly("jakarta.servlet:jakarta.servlet-api:6.1.0") // the server provides it
runtimeOnly("com.h2database:h2:2.4.240") // JDBC driver, loaded at run time
testImplementation(platform("org.junit:junit-bom:6.1.3"))
testImplementation("org.junit.jupiter:junit-jupiter")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
Compare the compile and runtime classpaths:
./gradlew dependencies --configuration compileClasspath -q
./gradlew dependencies --configuration runtimeClasspath -q
Output:
compileClasspath - Compile classpath for source set 'main'.
+--- com.google.code.gson:gson:2.13.2
| \--- com.google.errorprone:error_prone_annotations:2.41.0
\--- jakarta.servlet:jakarta.servlet-api:6.1.0
runtimeClasspath - Runtime classpath of source set 'main'.
+--- com.google.code.gson:gson:2.13.2
| \--- com.google.errorprone:error_prone_annotations:2.41.0
\--- com.h2database:h2:2.4.240
How it works:
- The servlet API is only on the compile classpath, so it is never packaged. H2 is only on the runtime classpath, so your code cannot
import org.h2...by accident. error_prone_annotationsis a transitive dependency: Gson needs it, so Gradle adds it automatically. The indented