Configure Gradle Build Cache

Last updated: September 21, 2026

What is Gradle Build Cache

The Gradle Build Cache saves significant build time by reusing Gradle Task outputs from previous builds when a task's inputs have not changed. Gradle Build Cache can be both Local and Remote.

For each Cacheable Task, Gradle hashes declared inputs into a cache key, then looks up that key in the Gradle Build Cache. On a cache miss Gradle runs the task slowly and stores the outputs; on a cache hit Gradle restores outputs quickly and skips the slow task run.

Importantly: like Bazel and Sbt, Gradle also caches Test runs, this allows teams to save significant CI time and cost.

Schematic example: say a first run of :libs:dto:compileKotlin with a few dozen Kotlin source files misses the cache, spends about 15 seconds compiling, and stores the resulting jar output file under the computed key:

Schematic Example of Gradle Cache Miss

:libs:dto:compileKotlin

  Inputs
  +----------------------+
  | UserDto.kt           |
  | ...                  |
  | Mapper.kt            |
  +----------+-----------+
             |
             v
  Compute cache key from inputs
             |
             v
  +----------------------+
  | Gradle Build Cache   |
  | key: a3f9...c2       |
  | status: MISS         |
  +----------+-----------+
             |
             v
  Compile Kotlin (~15s)
             |
             v
  Output: dto.jar
             |
             v
  Store dto.jar under key a3f9...c2

Later builds with the same inputs reuse that entry. Gradle computes the same cache key, hits the Remote Gradle Build Cache, and restores dto.jar in about 40ms instead of compiling for about 15 seconds.

Schematic Example of Gradle Cache Hit

:libs:dto:compileKotlin  (same inputs)

  Inputs unchanged
  UserDto.kt · ... · Mapper.kt
             |
             v
  Same cache key: a3f9...c2
             |
             v
  +----------------------+
  | Gradle Build Cache   |
  | key: a3f9...c2       |
  | status: HIT          |
  +----------+-----------+
             |
             v
  Download dto.jar (~40ms)
             |
             v
  Skip ~15s compile
  Task reports FROM-CACHE
  Build graph continues sooner

Remote Gradle Build Cache

For Gradle Build Cache outputs to be shared across machines, a Remote Gradle Build Cache must be configured. Local cache only helps on a single machine.

BuildFetch Cache natively implements the Gradle Build Cache remote protocols and acts as an extremely fast shared remote cache for CI, engineers, and AI agents.

A remote Gradle Build Cache lets teams share task outputs across engineer workstations, CI, and AI agent environments.

CI, having a more reproducible and controlled environment, typically both reads from and writes to the shared Gradle Build Cache. Engineers and AI agents read those outputs without uploading new entries.

That keeps the cache warm from reproducible CI builds while reducing repeated work on other machines.

Instead of recompiling, retesting, and repackaging on every machine, Gradle loads cached results and reports tasks as FROM-CACHE - turning builds that took minutes into cached builds that finish in seconds.

Cached Gradle Build Example

After CI populates the Gradle Build Cache, a clean build on another machine can resolve every expensive task from cache. In a typical scenario:

First build, where CI populates the Gradle Build Cache:

Schematic Example of Cold Build

$ ./gradlew clean assemble

> Task :compileJava
> Task :processResources
> Task :classes
> Task :compileTestJava
> Task :processTestResources
> Task :testClasses
> Task :test
> Task :jar
> Task :assemble

BUILD SUCCESSFUL in 10m 4s

Subsequent build, whether by an engineer, AI agent, or fresh CI agent can finish in seconds:

Schematic Example of Warm Build

$ ./gradlew clean assemble

> Task :compileJava FROM-CACHE
> Task :processResources FROM-CACHE
> Task :classes FROM-CACHE
> Task :compileTestJava FROM-CACHE
> Task :processTestResources FROM-CACHE
> Task :testClasses FROM-CACHE
> Task :test FROM-CACHE
> Task :jar FROM-CACHE
> Task :assemble FROM-CACHE

BUILD SUCCESSFUL in 4s

Enable Gradle Build Cache

Gradle Build Cache is disabled by default until you explicitly enable it.

We suggest enabling it for the whole Project with org.gradle.caching=true in gradle.properties and committing that file so CI, engineers, and AI agents all run with caching.

gradle.properties

org.gradle.caching=true

Alternatively you can pass the --build-cache flag in each individual Gradle invocation.

Configure Gradle Build Cache

Before setting up remote cache, ensure you have created BuildFetch Project and Token(s).

Official Gradle Build Cache documentation: https://docs.gradle.org/current/userguide/build_cache.html.

Gradle configuration is written in Kotlin or Groovy. Gradle Build Cache settings usually live in settings.gradle.kts.

Cache Access

Use a cache:readonly Token by default on developer and AI agent machines. Trusted environments like CI should use a cache:readwrite Token and explicitly enable uploads.

For Token management, rotation, and Open Source guidance, see Set up BuildFetch Cache Project.

Read-only

settings.gradle.kts

buildCache {
  remote<HttpBuildCache> {
    url = uri("<gradle build cache url>")

    credentials {
      username = "token-auth"
        
      // Set BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN="generated-token" as env variable (best for CI)
      // Set BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN="generated-token" in ~/.gradle/gradle.properties (best for mixed IDE and terminal experience)
      password = "BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN".let {
        providers.environmentVariable(it).orElse(providers.gradleProperty(it)).orNull
      }
    }

    isPush = providers.environmentVariable("CI").isPresent

    isEnabled = url != null && credentials.username != null && credentials.password != null
    }
}

Read-write

Bash

export BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN="<generated-readwrite-token>"
export CI=true

./gradlew build