gradle --build-cache: Reuse Task Outputs
gradle --build-cache lets Gradle pull task outputs from a local or remote cache instead of re-executing cacheable tasks, cutting build time.
The build cache is keyed on task inputs, so an unchanged compile or test can be fetched rather than re-run. On CI a shared remote cache turns cold runners warm.
What it does
With --build-cache, Gradle hashes the inputs of each cacheable task and looks up that key in the build cache. On a hit it copies the stored outputs and marks the task FROM-CACHE; on a miss it runs the task and stores the result. This is distinct from the up-to-date check, which is per-build.
Common usage
./gradlew build --build-cache
# enable permanently in gradle.properties
echo "org.gradle.caching=true" >> gradle.propertiesFlags
| Flag / property | What it does |
|---|---|
| --build-cache | Enable the build cache for this invocation |
| --no-build-cache | Disable it even if enabled in properties |
| org.gradle.caching=true | Enable by default (gradle.properties) |
| --info | Logs FROM-CACHE vs cache miss per task |
In CI
Cache the local build cache directory (~/.gradle/caches/build-cache-1) between jobs, or wire a remote cache so every runner shares outputs. Combine with caching ~/.gradle for dependencies. The gradle/actions setup-gradle action manages this for GitHub Actions.
Common errors in CI
Most "errors" are silent cache misses: with --info you will see a task run instead of FROM-CACHE because an input differed (an absolute path, a timestamp, or a non-reproducible jar). "Build cache is disabled" in the log means neither the flag nor the property is set. "Could not load entry ... from remote build cache" is a transient remote-cache fetch failure and is non-fatal.