Enable or disable the Gradle build cache: flag, property or settings

Gradle uses the build cache only when it is switched on and a cache is set up. Here is every way we tried to switch it on and off, with what each one did against a real cache server (release 0.2.1, Gradle 9.8.0).

The short answer

To turn it on for one build, add --build-cache.
To turn it on for everyone, put org.gradle.caching=true in gradle.properties.
To turn it off for one build, add --no-build-cache. It wins over the property.
Switching it on is not enough by itself: the project also needs the cache address in settings.gradle.kts.

What we ran

A four-module project with the cache address set in settings.gradle.kts (shown below). Each run used its own copy of the project and an empty Gradle home, so the only Gradle state shared was the cache server. An earlier set of runs started from a project folder that still held build output left over from an earlier test; we repeated all of them from a clean copy and got the same results. The table below shows the clean runs. We ran only :core:compileJava and looked at what Gradle printed next to it. Every build ended with BUILD SUCCESSFUL.

How it was switched	Command	Result
Flag (first build)	`gradle :core:compileJava --build-cache`	Ran, and saved the result to the server
Nothing set	`gradle :core:compileJava`	Ran. The cache was not used
Flag	`gradle :core:compileJava --build-cache`	`FROM-CACHE`
Property in `gradle.properties`	`org.gradle.caching=true`	`FROM-CACHE`
Property, and the flag off	`org.gradle.caching=true` and `--no-build-cache`	Ran. The flag won
System property	`gradle :core:compileJava -Dorg.gradle.caching=true`	`FROM-CACHE`
Flag, and rerun everything	`--build-cache --rerun-tasks`	Ran, even though a result was stored

Which one to use

Everyone, always: the property in gradle.properties, checked in with the project. New machines then need no flags.
CI only: pass --build-cache in the CI command and leave the property out.
A suspect build: run it with --no-build-cache to rule the cache out. If it stays broken, the cache is not the cause.
Force fresh work: --rerun-tasks makes Gradle redo the tasks even when a stored result exists.

The address still has to be set

This is the settings.gradle.kts we ran. Replace the address with your server's. We used 127.0.0.1 over plain HTTP because the test ran on one machine; use HTTPS across a network.

buildCache {
    local { isEnabled = false }
    remote<HttpBuildCache> {
        url = uri("http://127.0.0.1:18141/")
        isPush = true
        isAllowInsecureProtocol = true
    }
}

Read-only: turn off uploading, not the cache

Setting isPush = false lets a build download from the cache but never upload. We tried it against an empty server with the cache switched on. The build succeeded and ran the task, and the server still held 0 entries afterwards. A second build also ran the task, because nothing had ever been stored. Read-only only helps when someone else, such as CI, fills the cache. That setup is described in CI writes, developers read.

If you do not see FROM-CACHE

Work through why the hit rate is low and remote cache not working. To clear stored results, see reset the build cache.

Run on Gradle 9.8.0 with FosterStack Cache 0.2.1, macOS (arm64), Java 27.