The Gradle build cache is a cache mechanism that aims to save time by reusing outputs produced by other builds.
The build cache works by storing (locally or remotely) build outputs and allowing builds to fetch these outputs from the cache when it is determined that inputs have not changed, avoiding the expensive work of regenerating them.

A first feature using the build cache is task output caching.
Essentially, task output caching leverages the same intelligence as up-to-date checks that Gradle uses to avoid work when a previous local build has already produced a set of task outputs.
But instead of being limited to the previous build in the same workspace, task output caching allows Gradle to reuse task outputs from any earlier build in any location on the local machine.
When using a shared build cache for task output caching this even works across developer machines and build agents.

Apart from task output caching, we expect other features to use the build cache in the future.

✨

A complete guide is available about using the build cache. It covers the different scenarios caching can improve, and detailed discussions of the different caveats you need to be aware of when enabling caching for a build.

Beyond incremental builds described in up-to-date checks, Gradle can save time by reusing outputs from previous executions of a task by matching inputs to the task.
Task outputs can be reused between builds on one computer or even between builds running on different computers via a build cache.

We have focused on the use case where users have an organization-wide remote build cache that is populated regularly by continuous integration builds.
Developers and other continuous integration agents should load cache entries from the remote build cache.
We expect that developers will not be allowed to populate the remote build cache, and all continuous integration builds populate the build cache after running the clean task.

For your build to play well with task output caching it must work well with the incremental build feature.
For example, when running your build twice in a row all tasks with outputs should be UP-TO-DATE.
You cannot expect faster builds or correct builds when enabling task output caching when this prerequisite is not met.

Now we see that, instead of executing the :compileJava task, the outputs of the task have been loaded from the build cache.
The other tasks have not been loaded from the build cache since they are not cacheable. This is due to
:classes and :assemble being lifecycle tasks and :processResources
and :jar being Copy-like tasks which are not cacheable since it is generally faster to execute them.

Since a task describes all of its inputs and outputs, Gradle can compute a build cache key that uniquely defines the task’s outputs based on its inputs.
That build cache key is used to request previous outputs from a build cache or store new outputs in the build cache.
If the previous build outputs have been already stored in the cache by someone else, e.g. your continuous integration server or other developers, you can avoid executing most tasks locally.

The following inputs contribute to the build cache key for a task in the same way that they do for up-to-date checks:

Some tasks, like Copy or Jar, usually do not make sense to make cacheable because Gradle is only copying files from one location to another.
It also doesn’t make sense to make tasks cacheable that do not produce outputs or have no task actions.

There are third party plugins that work well with the build cache.
The most prominent examples are the Android plugin 3.1+ and the Kotlin plugin 1.2.21+.
For other third party plugins, check their documentation to find out whether they support the build cache.

It is very important that a cacheable task has a complete picture of its inputs and outputs, so that the results from one build can be safely re-used somewhere else.

Missing task inputs can cause incorrect cache hits, where different results are treated as identical because the same cache key is used by both executions.
Missing task outputs can cause build failures if Gradle does not completely capture all outputs for a given task.
Wrongly declared task inputs can lead to cache misses especially when containing volatile data or absolute paths.
(See the section called "Task inputs and outputs" on what should be declared as inputs and outputs.)

✨

The task path is not an input to the build cache key.
This means that tasks with different task paths can re-use each other’s outputs as long as Gradle determines that executing them yields the same result.

In order to ensure that the inputs and outputs are properly declared use integration tests (for example using TestKit) to check that a task produces the same outputs for identical inputs and captures all output files for the task.
We suggest adding tests to ensure that the task inputs are relocatable, i.e. that the task can be loaded from the cache into a different build directory (see @PathSensitive).

Gradle supports a local and a remote build cache that can be configured separately.
When both build caches are enabled, Gradle tries to load build outputs from the local build cache first, and then tries the remote build cache if no build outputs are found.
If outputs are found in the remote cache, they are also stored in the local cache, so next time they will be found locally.
Gradle stores ("pushes") build outputs in any build cache that is enabled and has BuildCache.isPush() set to true.

By default, the local build cache has push enabled, and the remote build cache has push disabled.

The built-in local build cache, DirectoryBuildCache, uses a directory to store build cache artifacts.
By default, this directory resides in the Gradle user home directory, but its location is configurable.

Gradle will periodically clean-up the local cache directory by removing entries that have not been used recently to conserve disk space.

For more details on the configuration options refer to the DSL documentation of DirectoryBuildCache.
Here is an example of the configuration.

Gradle has built-in support for connecting to a remote build cache backend via HTTP.
For more details on what the protocol looks like see HttpBuildCache.
Note that by using the following configuration the local build cache will be used for storing build outputs while the local and the remote build cache will be used for retrieving build outputs.

You may encounter problems with an untrusted SSL certificate when you try to use a build cache backend with an HTTPS URL.
The ideal solution is for someone to add a valid SSL certificate to the build cache backend, but we recognize that you may not be able to do that.
In that case, set HttpBuildCache.isAllowUntrustedServer() to true:

The recommended use case for the build cache is that your continuous integration server populates the remote build cache from clean builds while developers load from the remote build cache and store in the local build cache.
The configuration would then look as follows.

If you use a buildSrc directory, you should make sure that it uses the same build cache configuration as the main build.
This can be achieved by applying the same script to buildSrc/settings.gradle and settings.gradle as shown in the following example.

Gradle’s composite build feature allows including other complete Gradle builds into another.
Such included builds will inherit the build cache configuration from the top level build,
regardless of whether the included builds define build cache configuration themselves or not.

The build cache configuration present for any included build is effectively ignored, in favour of the top level build’s configuration.
This also applies to any buildSrc projects of any included builds.

Gradle provides a Docker image for a build cache node, which can connect with Gradle Enterprise for centralized management.
The cache node can also be used without a Gradle Enterprise installation with restricted functionality.