Configuration cache

When the configuration cache is enabled and you run Gradle for a particular set of tasks, for example by running gradlew check, Gradle checks whether a configuration cache entry is available for the requested set of tasks. If available, Gradle uses this entry instead of running the configuration phase. The cache entry contains information about the set of tasks to run, along with their configuration and dependency information.

The first time you run a particular set of tasks, there will be no entry in the configuration cache for these tasks and so Gradle will run the configuration phase as normal:

Following the configuration phase, Gradle writes the state of the task graph to the configuration cache, taking a snapshot for later Gradle invocations. The execution phase then runs as normal. This means you will not see any build performance improvement the first time you run a particular set of tasks.

When you subsequently run Gradle with this same set of tasks, for example by running gradlew check again, Gradle will load the tasks and their configuration directly from the configuration cache and skip the configuration phase entirely. Before using a configuration cache entry, Gradle checks that none of the "build configuration inputs", such as build scripts, for the entry have changed. If a build configuration input has changed, Gradle will not use the entry and will run the configuration phase again as above, saving the result for later reuse.

Build configuration inputs include:

Gradle uses its own optimized serialization mechanism and format to store the configuration cache entries. It automatically serializes the state of arbitrary object graphs. If your tasks hold references to objects with simple state or of supported types you don’t have anything to do to support the serialization.

As a fallback and to provide some aid in migrating existing tasks, some semantics of Java Serialization are supported. But it is not recommended relying on it, mostly for performance reasons.

Apart from skipping the configuration phase, the configuration cache provides some additional performance improvements:

By default, Gradle does not use the configuration cache. To enable the cache at build time, use the configuration-cache flag:

You can also enable the cache persistently in a gradle.properties file using the org.gradle.unsafe.configuration-cache property:

If enabled in a gradle.properties file, you can override that setting and disable the cache at build time with the no-configuration-cache flag:

By default, Gradle will fail the build if any configuration cache problems are encountered. When gradually improving your plugin or build logic to support the configuration cache it can be useful to temporarily turn problems into warnings.

This can be done from the command line:

or in a gradle.properties file:

When configuration cache problems are turned into warnings, Gradle will fail the build if 512 problems are found by default.

This can be adjusted by specifying an allowed maximum number of problems on the command line:

or in a gradle.properties file:

The configuration cache is automatically invalidated when inputs to the configuration phase change. However, certain inputs are not tracked yet, so you may have to manually invalidate the configuration cache when untracked inputs to the configuration phase change. This can happen if you ignored problems. See the Requirements and Not yet implemented sections below for more information.

The configuration cache state is stored on disk in a directory named .gradle/configuration-cache in the root directory of the Gradle build in use. If you need to invalidate the cache, simply delete that directory:

Configuration cache entries are checked periodically (at most every 24 hours) for whether they are still in use. They are deleted if they haven’t been used for 7 days.

In IntelliJ IDEA or Android Studio this can be done in two ways, either globally or per run configuration.

To enable it for the whole build, go to Run > Edit configurations…​. This will open the IntelliJ IDEA or Android Studio dialog to configure Run/Debug configurations. Select Templates > Gradle and add the necessary system properties to the VM options field.

For example to enable the configuration cache, turning problems into warnings, add the following:

You can also choose to only enable it for a given run configuration. In this case, leave the Templates > Gradle configuration untouched and edit each run configuration as you see fit.

Combining these two ways you can enable globally and disable for certain run configurations, or the opposite.

In Eclipse IDEs you can enable and configure the configuration cache through Buildship in two ways, either globally or per run configuration.

To enable it globally, go to Preferences > Gradle. You can use the properties described above as system properties. For example to enable the configuration cache, turning problems into warnings, add the following JVM arguments:

To enable it for a given run configuration, go to Run configurations…​, find the one you want to change, go to Project Settings, tick the Override project settings checkbox and add the same system properties as a JVM argument.

Combining these two ways you can enable globally and disable for certain run configurations, or the opposite.

Not all core Gradle plugins support configuration caching yet.

Please refer to issue gradle/gradle#13490 to learn about the status of community plugins.

It is possible to declare that a particular task is not compatible with the configuration cache via the Task.notCompatibleWithConfigurationCache() method.

Configuration cache problems found in tasks marked incompatible will no longer cause the build to fail.

And, when an incompatible task is scheduled to run, Gradle discards the configuration state at the end of the build. You can use this to help with migration, by temporarily opting out certain tasks that are difficult to change to work with the configuration cache.

Check the method documentation for more details.

There are a number of types that task instances must not reference from their fields. The same applies to task actions as closures such as doFirst {} or doLast {}.

These types fall into some categories as follows:

In all cases the reason these types are disallowed is that their state cannot easily be stored or recreated by the configuration cache.

Live JVM state types (e.g. ClassLoader, Thread, OutputStream, Socket etc…​) are simply disallowed. These types almost never represent a task input or output.

Gradle model types (e.g. Gradle, Settings, Project, SourceSet, Configuration etc…​) are usually used to carry some task input that should be explicitly and precisely declared instead.

For example, if you reference a Project in order to get the project.version at execution time, you should instead directly declare the project version as an input to your task using a Property<String>. Another example would be to reference a SourceSet to later get the source files, the compilation classpath or the outputs of the source set. You should instead declare these as a FileCollection input and reference just that.

The same requirement applies to dependency management types with some nuances.

Some types, such as Configuration or SourceDirectorySet, don’t make good task input parameters, as they hold a lot of irrelevant state, and it is better to model these inputs as something more precise. We don’t intend to make these types serializable at all. For example, if you reference a Configuration to later get the resolved files, you should instead declare a FileCollection as an input to your task. In the same vein, if you reference a SourceDirectorySet you should instead declare a FileTree as an input to your task.

Referencing dependency resolution results is also disallowed (e.g. ArtifactResolutionQuery, ResolvedArtifact, ArtifactResult etc…​). For example, if you reference some ResolvedComponentResult instances, you should instead declare a Provider<ResolvedComponentResult> as an input to your task. Such a provider can be obtained by invoking ResolutionResult.getRootComponent(). In the same vein, if you reference some ResolvedArtifactResult instances, you should instead use ArtifactCollection.getResolvedArtifacts() that returns a Provider<Set<ResolvedArtifactResult>> that can be mapped as an input to your task. The rule of thumb is that tasks must not reference resolved results, but lazy specifications instead, in order to do the dependency resolution at execution time.

Some types, such as Publication or Dependency are not serializable, but could be. We may, if necessary, allow these to be used as task inputs directly.

Here’s an example of a problematic task type referencing a SourceSet:

The following is how it should be done instead:

In the same vein, if you encounter the same problem with an ad-hoc task declared in a script as follows:

You still need to fulfil the same requirement, that is not referencing a disallowed type. Here’s how the task declaration above can be fixed:

Note that sometimes the disallowed type is indirectly referenced. For example, you could have a task reference some type from a plugin that is allowed. That type could reference another allowed type that in turn references a disallowed type. The hierarchical view of the object graph provided in the HTML reports for problems should help you pinpoint the offender.

A task must not use any Project objects at execution time. This includes calling Task.getProject() while the task is running.

Some cases can be fixed in the same way as for disallowed types.

Often, similar things are available on both Project and Task. For example if you need a Logger in your task actions you should use Task.logger instead of Project.logger.

Otherwise, you can use injected services instead of the methods of Project.

Here’s an example of a problematic task type using the Project object at execution time:

The following is how it should be done instead:

In the same vein, if you encounter the same problem with an ad-hoc task declared in a script as follows:

Here’s how the task declaration above can be fixed:

As you can see above, fixing ad-hoc tasks declared in scripts requires quite a bit of ceremony. It is a good time to think about extracting your task declaration as a proper task class as shown previously.

The following table shows what APIs or injected service should be used as a replacement for each of the Project methods.

Tasks should not directly access the state of another task instance. Instead, tasks should be connected using inputs and outputs relationships.

Note that this requirement makes it unsupported to write tasks that configure other tasks at execution time.

Plugins and build scripts must not register any build listeners. That is listeners registered at configuration time that get notified at execution time. For example a BuildListener or a TaskExecutionListener.

These should be replaced by build services, registered to receive information about task execution if needed.

Plugin and build scripts should avoid running external processes at configuration time. In general, it is preferred to run external processes in tasks with properly declared inputs and outputs to avoid unnecessary work when the task is up-to-date. If necessary, only configuration-cache-compatible APIs should be used instead of Java and Groovy standard APIs or existing ExecOperations, Project.exec, Project.javaexec, and their likes in settings and init scripts. For simpler cases, when grabbing the output of the process is enough, providers.exec() and providers.javaexec() can be used:

For more complex cases a custom ValueSource implementation with injected ExecOperations can be used. This ExecOperations instance can be used at configuration time without restrictions.

The ValueSource implementation can then be used to create a provider with providers.of:

In both approaches, if the value of the provider is used at configuration time then it will become a build configuration input. The external process will be executed for every build to determine if the configuration cache is up-to-date, so it is recommended to only call fast-running processes at configuration time. If the value changes then the cache is invalidated and the process will be run again during this build as part of the configuration phase.

Plugins and build scripts may read system properties and environment variables directly at configuration time with standard Java, Groovy, or Kotlin APIs or with the value supplier APIs. Doing so makes such variable or property a build configuration input, so changing the value invalidates the configuration cache. The configuration cache report includes a list of these build configuration inputs to help track them.

In general, you should avoid reading the value of system properties and environment variables at configuration time, to avoid cache misses when value changes. Instead, you can connect the Provider returned by providers.systemProperty() or providers.environmentVariable() to task properties.

Some access patterns that potentially enumerate all environment variables or system properties (for example, calling System.getenv().forEach() or using the iterator of its keySet()) are discouraged. In this case, Gradle cannot find out what properties are actual build configuration inputs, so every available property becomes one. Even adding a new property will invalidate the cache if this pattern is used.

Using a custom predicate to filter environment variables is an example of this discouraged pattern:

The logic in the predicate is opaque to the configuration cache, so all environment variables are considered inputs. One way to reduce the number of inputs is to always use methods that query a concrete variable name, such as getenv(String), or getenv().get():

The fixed code above, however, is not exactly equivalent to the original as only an explicit list of variables is supported. Prefix-based filtering is a common scenario, so there are provider-based APIs to access system properties and environment variables:

Note that the configuration cache would be invalidated not only when the value of the variable changes or the variable is removed but also when another variable with the matching prefix is added to the environment.

For more complex use cases a custom ValueSource implementation can be used. System properties and environment variables referenced in the code of the ValueSource do not become build configuration inputs, so any processing can be applied. Instead, the value of the ValueSource is recomputed each time the build runs and only if the value changes the configuration cache is invalidated. For example, a ValueSource can be used to get all environment variables with names containing the substring JDK:

Plugins and build scripts should not read files directly using the Java, Groovy or Kotlin APIs at configuration time. Instead, declare files as potential build configuration inputs using the value supplier APIs.

This problem is caused by build logic similar to this:

To fix this problem, read files using providers.fileContents() instead:

In general, you should avoid reading files at configuration time, to avoid invalidating configuration cache entries when the file content changes. Instead, you can connect the Provider returned by providers.fileContents() to task properties.

For security reasons, the configuration cache does not store credentials declared inline.

To use credentials in build scripts with the configuration cache, declare credentials with Gradle Properties. To learn more about using credentials with Gradle Properties, check out the example in the credential handling documentation.

The configuration cache is currently stored locally only. It can be reused by hot or cold local Gradle daemons. But it can’t be shared between developers or CI machines.

See gradle/gradle#13510.

When there’s no configuration cache available and the work graph needs to be calculated, tasks are not executed in parallel by default. Only builds that reuse the configuration cache currently execute all tasks in parallel by default.

See gradle/gradle#14624.

Support for source dependencies is not yet implemented. With the configuration cache enabled, no problem will be reported and the build will fail.

See gradle/gradle#13506.

When running builds using TestKit, the configuration cache can interfere with Java agents, such as the Jacoco agent, that are applied to these builds.

Currently, all external sources of Gradle properties (gradle.properties in project directories and in the GRADLE_USER_HOME, environment variables and system properties that set properties, and properties specified with command-line flags) are considered build configuration inputs regardless of what properties are actually used at configuration time. These sources, however, are not included in the configuration cache report.

Gradle allows objects that support the Java Object Serialization protocol to be stored in the configuration cache.

The implementation is currently limited to serializable classes that implement the java.io.Serializable interface and define one of the following combination of methods:

The following Java Object Serialization features are not supported:

See gradle/gradle#13588.

Currently, Gradle cannot restore objects from the configuration cache that store user-provided lambdas. For example, if an object provides a method that accepts a Single Abstract Method (SAM) interface argument (e.g. a Function argument), it is natural to implement this argument as a lambda. If the lambda is then stored in the object for later invocation, the object will not be compatible with the configuration cache and will cause a failure when restored. Instead of a lambda, the argument should be provided as a typed object implementing the SAM interface.

Alternatively, for Kotlin implementations, the Kotlin compiler can be configured to generate classes instead of lambdas during SAM conversion.