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 a snapshot of the task graph to a new configuration cache entry, for later Gradle invocations. Gradle then loads the task graph from the configuration cache, so that it can apply optimizations to the tasks, and then runs the execution phase as normal. Configuration time will still be spent the first time you run a particular set of tasks. However, you should see build performance improvement immediately because tasks will run in parallel.

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.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, with no guarantee that the build will work.

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:

Configuration cache storing and loading are done sequentially by default. Parallel storing and loading provide better performance, however not all builds are compatible with it.

To enable parallel configuration caching on the command line:

or in a gradle.properties file:

The parallel configuration caching feature is incubating, as not all builds are guaranteed to work correctly. Common symptoms are ConcurrentModificationException exceptions during the configuration phase. The feature should work well for decoupled multi-project builds.

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.

Build logic or plugin implementations can detect if the configuration cache is enabled for a given build, and react to it accordingly. The active status of the configuration cache is provided in the corresponding build feature. You can access it by injecting the BuildFeatures service into your code.

You can use this information to configure features of your plugin differently or to disable an optional feature that is not yet compatible. Another example involves providing additional guidance for your users, should they need to adjust their setup or be informed of temporary limitations.

Gradle releases bring enhancements to the configuration cache, making it detect more cases of configuration logic interacting with the environment. Those changes improve the correctness of the cache by eliminating potential false cache hits. On the other hand, they impose stricter rules that plugins and build logic need to follow to be cached as often as possible.

Some of those configuration inputs may be considered "benign" if their results do not affect the configured tasks. Having new configuration misses because of them may be undesirable for the build users, and the suggested strategy for eliminating them is:

It is possible to temporarily opt out of configuration input detection in the following cases:

Ignore configuration inputs sparingly, and only if they do not affect the tasks produced by the configuration logic. The support for these options will be removed in future releases.

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. The only exceptions are the standard streams: System.in, System.out, and System.err. These streams can be used, for example, as parameters to Exec and JavaExec tasks.

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.

When storing a task to the configuration cache, all objects directly or indirectly referenced through the task’s fields are serialized. In most cases, deserialization preserves reference equality: if two fields a and b reference the same instance at configuration time, then upon deserialization they will reference the same instance again, so a == b (or a === b in Groovy and Kotlin syntax) still holds. However, for performance reasons, some classes, in particular java.lang.String, java.io.File, and many implementations of java.util.Collection interface, are serialized without preserving the reference equality. Upon deserialization, fields that referred to the object of such a class can refer to different but equal objects.

Let’s look at a task that stores a user-defined object and an ArrayList in task fields.

Running the build without the configuration cache shows that reference equality is preserved in both cases.

However, with the configuration cache enabled, only the user-defined object references are the same. List references are different, though the referenced lists are equal.

In general, it isn’t recommended to share mutable objects between configuration and execution phases. If you need to do this, you should always wrap the state in a class you define. There is no guarantee that the reference equality is preserved for standard Java, Groovy, and Kotlin types, or for Gradle-defined types.

Note that no reference equality is preserved between tasks: each task is its own "realm", so it is not possible to share objects between tasks. Instead, you can use a build service to wrap the shared state.

Tasks should not access conventions and extensions, including extra properties, at execution time. Instead, any value that’s relevant for the execution of the task should be modeled as a task property.

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. Use dataflow actions to handle the build result instead of buildFinished listeners.

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. However, if needed, you should only use the configuration-cache-compatible APIs described below, instead of Java and Groovy standard APIs, or Gradle-provided methods Project.exec, Project.javaexec, ExecOperations.exec, and ExecOperations.javaexec. The flexibility of these methods prevents Gradle from determining how the calls impact the build configuration, making it difficult to ensure that the configuration cache entry can be safely reused.

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.

You can also use standard Java/Kotlin/Groovy process APIs like java.lang.ProcessBuilder in the ValueSource.

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.

To detect the configuration inputs, Gradle modifies the bytecode of classes on the build script classpath, like plugins and their dependencies. Gradle uses a Java agent to modify the bytecode. Integrity self-checks of some libraries may fail because of the changed bytecode or the agent’s presence.

To work around this, you can use the Worker API with classloader or process isolation to encapsulate the library code. The bytecode of the worker’s classpath is not modified, so the self-checks should pass. When process isolation is used, the worker action is executed in a separate worker process that doesn’t have the Gradle Java agent installed.

In simple cases, when the libraries also provide command-line entry points (public static void main() method), you can also use the JavaExec task to isolate the library.

By default, Gradle automatically generates and manages the encryption key as a Java keystore stored under the GRADLE_USER_HOME directory.

For environments where this is undesirable (for instance, when the GRADLE_USER_HOME directory is shared across machines), you may provide Gradle with the exact encryption key to use when reading or writing the cached configuration data via the GRADLE_ENCRYPTION_KEY environment variable.

For Gradle to encrypt the configuration cache using a user-specified encryption key, you must run Gradle while having the GRADLE_ENCRYPTION_KEY environment variable set with a valid AES key, encoded as a Base64 string.

One way of generating a Base64-encoded AES-compatible key is by using a command like this:

This command should work on Linux, Mac OS, or on Windows, if using a tool like Cygwin.

You can then use the Base64-encoded key produced by that command and set it as the value of the GRADLE_ENCRYPTION_KEY environment variable.

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.

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.

See gradle/gradle#25979.

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.

See gradle/gradle#20969.

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 either implement the java.io.Externalizable interface, or 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.

A common approach to reuse logic and data in a build script is to extract repeating bits into top-level methods and variables. However, calling such methods at execution time is not currently supported if the configuration cache is enabled.

For builds scripts written in Groovy, the task fails because the method cannot be found. The following snippet uses a top-level method in the listFiles task:

Running the task with the configuration cache enabled produces the following error:

To prevent the task from failing, convert the referenced top-level method to a static method within a class:

Build scripts written in Kotlin cannot store tasks that reference top-level methods or variables at execution time in the configuration cache at all. This limitation exists because the captured script object references cannot be serialized. The first run of the Kotlin version of the listFiles task fails with the configuration cache problem.

To make the Kotlin version of this task compatible with the configuration cache, make the following changes:

See gradle/gradle#22879.

Currently, it is impossible to use a BuildServiceProvider or provider derived from it with map or flatMap as a parameter for the ValueSource, if the value of the ValueSource is accessed at configuration time. The same applies when such a ValueSource is obtained in a task that executes as part of the configuration phase, for example tasks of the buildSrc build or included builds contributing plugins. Note that using a @ServiceReference or storing BuildServiceProvider in an @Internal-annotated property of a task is safe. Generally speaking, this limitation makes it impossible to use a BuildService to invalidate the configuration cache.

See gradle/gradle#24085.