skip to content

How do you turn on Gradle's configuration cache for a build, and what are the two main ways to do it?

level: juniorimportance: must knowfreq 70%

answer

  1. --configuration-cache flag
  2. org.gradle.configuration-cache=true
  3. gradle.properties (project or ~/.gradle)
  4. --no-configuration-cache overrides
  5. caches the task graph, not outputs

basics

~10 s

Pass --configuration-cache on the command line for a single run, or set org.gradle.configuration-cache=true in gradle.properties to enable it persistently for every build.

solid answer

~30 s

There are two ways. For a one-off run, add the `--configuration-cache` flag, e.g. `./gradlew build --configuration-cache`. To enable it permanently for the project, put `org.gradle.configuration-cache=true` in `gradle.properties` (committed for the team, or in `~/.gradle/gradle.properties` per-developer). The command-line flag wins over the property for that invocation, and `--no-configuration-cache` force-disables it even if the property is set. When enabled, Gradle caches the result of the *configuration phase* (the task graph) keyed by inputs like the requested tasks, build scripts, and environment, so subsequent compatible runs skip configuration entirely and go straight to executing tasks.

code

bash · 8 lines
bash
# one-off
./gradlew build --configuration-cache

# persistent: gradle.properties
# org.gradle.configuration-cache=true

# force off for one run even if the property is set
./gradlew build --no-configuration-cache

go deeper

for a junior

Name both mechanisms: the --configuration-cache flag and org.gradle.configuration-cache=true in gradle.properties.

for a middle

Explain precedence (flag beats property, --no- overrides), where to put the property (project vs ~/.gradle), and that it caches the task graph.

for a senior

Tie it to the build phases, explain the cache key (requested tasks + config inputs), and contrast clearly with the build cache.

for a principal

Discuss rollout policy: committing the property for the whole team vs per-developer opt-in, and the interaction with reproducible config inputs across machines.

## What the configuration cache is A Gradle build runs in phases: **initialization** (settle which projects participate), **configuration** (run every `build.gradle(.kts)` script to build the in-memory *task graph*), and **execution** (run the selected tasks). The configuration phase can be expensive on large multi-project builds. The **configuration cache** stores a serialized snapshot of the configured task graph so that, on a later run with the *same inputs*, Gradle skips configuration entirely and goes straight to execution. It is distinct from the **build cache** (which caches *task outputs*) — configuration cache caches the *task graph itself*. ## Two ways to enable it 1. **Per-invocation flag:** `./gradlew assemble --configuration-cache`. Good for trying it out without committing anything. 2. **Project/user property:** add to `gradle.properties`: ``` org.gradle.configuration-cache=true ``` Put it in the project's `gradle.properties` to enable it for everyone, or in `~/.gradle/gradle.properties` to opt in just for yourself. ## Precedence The command line beats the property for that run. `--configuration-cache` forces it on; `--no-configuration-cache` forces it off even when the property says `true`. This lets you disable it ad hoc to debug a flaky build. ## The cache key The cache entry is keyed on the **set of requested task names plus the build configuration inputs** — build script contents, plugin versions, and any environment/system-property/file inputs the configuration phase read. Change any of those and Gradle computes a *miss* and reconfigures, storing a fresh entry. ## What you see On a store, Gradle prints `Calculating task graph as no configuration cache is available for tasks: <tasks>`. On a hit, it prints `Reusing configuration cache.` — the signal that configuration was skipped. ```bash # first run — stores the entry ./gradlew assemble --configuration-cache # > Calculating task graph as no configuration cache is available... # second identical run — reuses it ./gradlew assemble --configuration-cache # > Reusing configuration cache. ```

  • If org.gradle.configuration-cache=true is set but you pass --no-configuration-cache, what happens?
    The command-line flag wins for that invocation, so the configuration cache is disabled for that run only; the property still applies to subsequent runs.
  • How is the configuration cache different from the build cache?
    The build cache caches task *outputs* keyed by task inputs; the configuration cache caches the *task graph* produced by the configuration phase. They are independent and can be used together.

saying these in an interview costs you the question

  • Confusing the configuration cache with the build cache (output cache).
  • Claiming the property goes in settings.gradle — it goes in gradle.properties.
  • Thinking the flag caches task outputs rather than the task graph.

context

resolving links…