Configuration Cache

The first time you run a set of tasks, there is no cache entry. Gradle performs the configuration phase as usual:

Gradle then stores a snapshot of the task graph in the Configuration Cache for future use. After this, Gradle loads the task graph from the cache and proceeds with task execution.

On subsequent executions of the same tasks (e.g., gradlew check again), Gradle:

Before using the cache, Gradle verifies that no build configuration inputs have changed. If any input has changed, Gradle reruns the configuration phase and updates the cache.

The following elements determine whether a Configuration Cache entry is valid:

Gradle uses an optimized serialization mechanism to store Configuration Cache entries. It automatically serializes object graphs containing simple state or supported types.

While Configuration Cache serialization doesn’t rely on Java Serialization, it understands some of its features. This can be used to customize serialization behavior, but incurs performance penalty and should be avoided.

Beyond skipping the configuration phase, the Configuration Cache enhances performance in the following ways:

By default, Gradle fails the build if Configuration Cache problems occur. However, when gradually updating plugins or build logic to support the Configuration Cache, it can be useful to temporarily turn problems into warnings.

To change this behavior at build time, use the following flag:

Alternatively, configure it in gradle.properties:

When Configuration Cache problems are treated as warnings, Gradle will fail the build if 512 problems are found by default.

You can adjust this limit by specifying the maximum number of allowed problems on the command line:

Or configure it in a gradle.properties file:

By default, Configuration Cache storing and loading are sequential. Enabling parallel storing and loading can improve performance, but not all builds are compatible with it.

To enable parallel configuration caching at build time, use:

Or persistently in a gradle.properties file:

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.

Using these methods together, you can enable the Configuration Cache globally while disabling it for certain run configurations, or vice versa.

In Eclipse-based IDEs, you can enable the Configuration Cache through Buildship, either globally or per run configuration.

To enable it globally:

To enable it for a specific run configuration:

Using these methods together, you can enable the Configuration Cache globally while disabling it for certain run configurations, or vice versa.

Most Core Gradle Plugins support configuration caching at this time:

Please refer to issue gradle/gradle#13490 to learn about the status of Community Plugins.

You can explicitly mark a task as incompatible with the Configuration Cache using the Task.notCompatibleWithConfigurationCache() method:

When a task is marked as incompatible:

This mechanism can be useful during migration, allowing you to temporarily opt out tasks that require more extensive changes to become Configuration Cache-compatible.

For more details, refer to the method documentation.

To reduce entry size and improve performance, Gradle performs minimal integrity checks when writing and reading data. However, this approach can make troubleshooting issues more difficult, especially when dealing with concurrency problems or serialization errors. An incorrectly stored object may not be detected immediately but could lead to misleading or misattributed errors when reading cached data later.

To make debugging easier, Gradle provides an option to enable stricter integrity checks. This setting helps identify inconsistencies earlier but may slow down cache operations and significantly increase the cache entry size. To enable stricter integrity checks, add the following line to your gradle.properties file:

For example, let’s look at a type that implements a custom serialization protocol incorrectly:

Such a type will cause problems when used as part of a task state, because the configuration cache will try to interpret the remaining unread part of the object as some new value:

When running without the integrity check, you may encounter cryptic failure messages, possibly accompanied by induced configuration cache problems:

These errors might not immediately point to the root cause, making debugging more challenging. It might be really hard to connect an invalid index error to a serialization issue, for example.

Rerunning the build with the integrity check enabled provides a much more precise diagnostic, helping you pinpoint the source of the issue faster:

You can immediately see the name of the offending task and the field that contains the broken data.

Keep in mind that this attribution is best-effort: it should be accurate in most cases, but in rare instances, it may be confused by certain byte patterns.

The current integrity checks primarily focus on identifying serialization protocol issues rather than general data corruption. Consequently, they are less effective against hardware-related problems, such as bit rot or damaged storage sectors. Due to these limitations and the performance overhead introduced by integrity checks, we recommend enabling them selectively as a troubleshooting measure rather than leaving them permanently enabled.

Build logic or plugin implementations can detect whether the Configuration Cache is enabled for a given build and adjust behavior 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.

This information can be used to:

Gradle releases continuously enhance the Configuration Cache by detecting more cases where configuration logic interacts with the environment. These improvements increase cache correctness by preventing false cache hits but also introduce stricter rules that plugins and build logic must follow for optimal caching.

Some newly detected configuration inputs may not impact the configured tasks but can still cause cache invalidation. To minimize unnecessary cache misses, follow these steps:

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

Use these opt-out options sparingly and only if they do not impact task execution results. These options are intended as temporary workarounds and will be removed in future Gradle releases.

Some types must not be referenced by task fields or in task actions (such as doFirst {} or doLast {}).

These types fall into the following categories:

These restrictions exist because these types cannot easily be stored or reconstructed by the Configuration Cache.

Tasks must not use any Project objects during execution. This includes calling Task.getProject() while a task is running.

Some cases can be resolved similarly to those described in disallowed types.

Often, equivalent functionality is available on both Project and Task. For example:

The following task incorrectly references the Project object at execution time:

Fixed version:

If the same problem occurs in an ad-hoc task in a script:

Fixed version:

Fixing ad-hoc tasks in scripts requires additional effort, making it a good opportunity to refactor them into proper task classes.

The table below lists recommended replacements for commonly used Project methods:

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

This requirement ensures that tasks remain isolated and correctly cacheable. As a result, it is unsupported to write tasks that configure other tasks at execution time.

When storing a task in the Configuration Cache, all objects 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, they will still reference the same instance after deserialization (a == b, or a === b in Groovy/Kotlin syntax).

However, for performance reasons, certain classes—such as java.lang.String, java.io.File, and many java.util.Collection implementations—are serialized without preserving reference equality. After deserialization, fields that referred to these objects may reference different but equal instances.

Consider a task that stores a user-defined object and an ArrayList as task fields:

Without Configuration Cache, reference equality is preserved in both cases:

With Configuration Cache enabled, only user-defined object references remain identical. List references are different, although the lists themselves remain equal:

Best Practices:

Reference equality is never preserved between tasks—each task is an isolated "realm." To share objects across tasks, use a Build Service to wrap the shared state.

Tasks must not access conventions, extensions, or extra properties at execution time.

Instead, any value relevant to task execution should be explicitly modeled as a task property to ensure proper caching and reproducibility.

Plugins and build scripts must not register build listeners that are created at configuration time and triggered at execution time. This includes listeners such as BuildListener or TaskExecutionListener.

Recommended Alternatives:

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 variables or properties a build configuration input. Therefore, changing their 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 these values change. 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 behavior is undesirable—such as when the GRADLE_USER_HOME directory is shared across multiple machines—you can explicitly provide an encryption key using the GRADLE_ENCRYPTION_KEY environment variable.

To encrypt the Configuration Cache using a user-specified encryption key, Gradle requires the GRADLE_ENCRYPTION_KEY environment variable to be set with a valid AES key, encoded as a Base64 string.

You can generate a Base64-encoded AES-compatible key using the following command:

This command works on Linux and macOS, and on Windows if using a tool like Cygwin.

Once generated, set the Base64-encoded key as the value of the GRADLE_ENCRYPTION_KEY environment variable:

The Configuration Cache is currently stored locally only. It can be reused by both hot and cold local Gradle daemons, but it cannot 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—such as gradle.properties files (both in project directories and in the GRADLE_USER_HOME), environment variables, system properties that set properties, and properties specified via command-line flags—are considered build configuration inputs, regardless of whether they are actually used during configuration.

However, these sources 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.