Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Dependencies and Repositories

Declaring Dependencies: implementation, api, runtimeOnly and More

Declare Gradle dependencies correctly: coordinates, implementation vs api, compileOnly, runtimeOnly, testImplementation, project dependencies and configuration inheritance.

Almost every project uses libraries written by others. In Gradle you declare them in the dependencies { } block, and you decide where each library is needed: to compile the main code, only at run time, or only for tests. That decision is called the configuration (or dependency scope), and choosing it well keeps builds fast, jars small and APIs clean. This lesson covers coordinates, the standard configurations of the Java plugins and how they relate.

The Gradle code is read-only; the stand-ins parse coordinates and model configuration inheritance in Java.

Coordinates

A published library is identified by three parts, often written group:name:version:

TEXT
com.google.guava:guava:33.4.0-jre
 ^ group          ^ name   ^ version
  • group is a reverse-domain namespace (org.slf4j, com.fasterxml.jackson.core).
  • name (the artifact) is the library.
  • version selects the release. Some libraries add a classifier (:linux-x86_64) or an extension (@aar).
Kotlin
dependencies {
    implementation("com.google.guava:guava:33.4.0-jre")
    implementation(group = "org.slf4j", name = "slf4j-api", version = "2.0.16")   // long form
}

The standard configurations

The Java plugin defines these dependency configurations:

Configuration Available at compile time Available at run time Visible to consumers
implementation yes yes no (hidden from consumers' compile classpath)
api (java-library) yes yes yes
compileOnly yes no no
runtimeOnly no yes no (at run time yes)
testImplementation tests only tests only no
testRuntimeOnly no tests only no
annotationProcessor annotation processing only no no
Kotlin
plugins { `java-library` }

dependencies {
    api("org.apache.commons:commons-lang3:3.17.0")        // part of my public API
    implementation("com.google.guava:guava:33.4.0-jre")   // an internal detail
    compileOnly("org.projectlombok:lombok:1.18.36")       // needed to compile, not shipped
    annotationProcessor("org.projectlombok:lombok:1.18.36")
    runtimeOnly("org.postgresql:postgresql:42.7.4")       // only needed when running
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

implementation vs api

Suppose library core depends on Guava, and app web depends on core.

  • If core declares Guava with implementation, web can use core but cannot see Guava at compile time. Guava is an internal detail, and if core upgrades or drops it, web does not need recompiling.
  • If core declares it with api, Guava appears in the public signatures of core (for example a method returns a Guava type), so web needs it to compile.

Use implementation by default and api only for types you expose. api exists only with the java-library plugin; the plain java plugin has implementation only. The benefit is faster, more incremental builds: fewer modules recompile when an internal dependency changes.

Configuration inheritance

Configurations extend each other. testImplementation extends implementation, so tests see everything main code sees. The classpaths that actually go to the compiler and the JVM are resolvable configurations built from the declaring ones:

flowchart TD
  A["api"] --> B["implementation"]
  B --> C["compileClasspath"]
  D["compileOnly"] --> C
  B --> E["runtimeClasspath"]
  F["runtimeOnly"] --> E
  B --> G["testImplementation"]
  G --> H["testCompileClasspath"]
  I["testRuntimeOnly"] --> J["testRuntimeClasspath"]
  G --> J

You declare dependencies in the left boxes; Gradle resolves the classpaths on the right.

You can print what a configuration resolved to with ./gradlew dependencies --configuration runtimeClasspath.

Stand-in: parsing coordinates

This is not Gradle. It parses the string notation into its parts, the first thing a dependency handler does.

Java Stand-in: group:name:version

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.

A notation without a version is legal in Gradle when something else supplies the version (a platform or a version catalog, covered later).

Stand-in: which classpath sees which dependency?

The second stand-in models the inheritance table: each declared dependency lands on the classpaths that include its configuration.

Java Stand-in: building the classpaths

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.

You can read the result as a table: lombok is only on the compile classpaths, postgresql only on the run-time ones, and junit only in the test classpaths.

Project and file dependencies

Kotlin
dependencies {
    implementation(project(":core"))            // another project in the same build
    implementation(files("libs/legacy.jar"))     // a local jar; last resort
    implementation(fileTree("libs") { include("*.jar") })
}

Prefer project dependencies for internal modules and repositories for external ones. Local jars have no metadata, so Gradle cannot resolve their transitive dependencies or update them.

Dynamic and snapshot versions

"1.+" or "latest.release" select a version at resolution time, and -SNAPSHOT versions can change over time. Both make builds irreproducible. Use fixed versions, and update them deliberately (for instance with dependency locking or a bot).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which configuration puts a dependency on the run-time classpath only?

    runtimeOnly dependencies (for example a JDBC driver) are needed to run, not to compile.
  2. 2. When should a java-library project declare a dependency with api?

    api exposes the dependency to consumers' compile classpath. Use implementation for internal use.
  3. 3. What does the notation com.google.guava:guava:33.4.0-jre contain?

    A dependency is identified by group, name (artifact) and version.
  4. 4. Why are dynamic versions like 1.+ discouraged?

    The same build can resolve different versions on different days, which makes failures hard to reproduce.

Summary

  • Dependencies are identified by group:name:version and declared in dependencies { }.
  • implementation is the default; api only for types exposed by a library; compileOnly for compile-time-only needs; runtimeOnly for run-time-only needs.
  • testImplementation and testRuntimeOnly are for tests; annotation processors have their own configuration.
  • Declaring configurations feed the resolvable compileClasspath, runtimeClasspath and test classpaths.
  • Use project(":x") for internal modules; avoid local jars and dynamic versions.

Next: Repositories and Version Catalogs