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. FosterStack Cache is a remote build cache server for Gradle, and this page shows how to switch the build cache on and off.

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.
• The configuration cache is a different feature. It does not use the server.

Which one to use

Our advice, not a test result.

• 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.

Gradle configuration cache vs build cache

They sound alike and they are not the same thing. One saves Gradle from working out your build again. The other saves your tasks from running again. You can use both, and only the second one uses a cache server.

A remote cache server such as FosterStack Cache is for the build cache only. If Gradle suggests enabling the configuration cache, that is a separate local feature and has nothing to do with the server.

Our advice, not a test result. They solve different problems. The configuration cache helps most on large builds, where planning takes a while. The build cache helps most where the same work is done on many machines, such as CI runners and developer laptops. To set up a shared build cache, start with your first 15 minutes with the build cache.

If you do not see FROM-CACHE

Work through remote cache not working, which also covers a low hit rate. To clear stored results, see reset the build cache. For the authentication errors, see authentication and 401 errors.

How we checked

Switching the cache on and off

A four-module project with the cache address set in settings.gradle.kts (shown above). 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.

Configuration cache and build cache together

The same small project, both flags on, the build cache pointed at a server. We ran this on Gradle 9.8.0 and a 0.2.1 server:

gradle build --configuration-cache --build-cache

1. The first build. In our runs, nothing was cached anywhere:

Calculating task graph as no cached configuration is available for tasks: build
> Task :compileJava
BUILD SUCCESSFUL in 5s
Configuration cache entry stored.

2. The same build again. Both caches work, in different ways. The plan is reused, and the task is simply up to date on disk:

Reusing configuration cache.
> Task :compileJava UP-TO-DATE
BUILD SUCCESSFUL in 1s
Configuration cache entry reused.

3. After gradle clean. The build outputs are gone, so the task would have to run again. The plan is still reused, and the output now comes from the server:

Reusing configuration cache.
> Task :compileJava FROM-CACHE
BUILD SUCCESSFUL in 1s
Configuration cache entry reused.

In our runs, the server's status page counted one hit for that, and it holds the compiled output only.

4. After editing build.gradle.kts, then gradle clean. Now the configuration cache is thrown away, because a build file changed, but the build cache still works, because the task's inputs did not change:

Calculating task graph as configuration cache cannot be reused because file 'build.gradle.kts' has changed.
> Task :compileJava FROM-CACHE
BUILD SUCCESSFUL in 2s
Configuration cache entry stored.

That fourth step is the clearest way to see they are separate: in our runs, one was invalidated and the other was not.

The on/off runs: Gradle 9.8.0 with FosterStack Cache 0.2.1, macOS (arm64), Java 27.

We ran the page again on a GitHub-hosted Linux machine with FosterStack Cache 0.2.2, Gradle 9.8.0 and Java 21. The seven on/off runs (a four-module project), the read-only run and the four configuration-cache steps (a one-module project) all gave the results and lines shown above (timings aside). The server's status page counted one hit in step 3. The run and its log are public.