Isolated Projects is a pre-alpha Gradle feature that extends the configuration cache to further improve performance, particularly the performance of Android Studio and IDEA sync.

When Isolated Projects is enabled, the configuration model of Gradle projects are "isolated" from each other. This means that build logic, such as build scripts or plugins, applied to a project cannot directly access the mutable state of another project. This allows configuration and tooling model creation for each project to safely run in parallel, with the result cached and invalidated independently for each project.

Status as of Gradle 8.11

When Isolated Projects is enabled, Gradle applies two levels of caching during IDE sync:

  1. Gradle starts by applying coarse-grained caching.

    To do this, Gradle caches the result of the entire sync operation and reuses it when nothing that affects the IDE model has changed. When the cache entry can be reused, Gradle short-circuits the entire sync operation and returns the cached result to the IDE.

  2. Generally, the settings and build scripts affect the IDE model, but the project’s source code does not. So, when these scripts change, the cache entry cannot be reused. When this happens, Gradle falls back to fine-grained caching.

    To do this, Gradle caches the result of creating the tooling models for each project and reuses these models when nothing that affects them has changed. When a project’s cached models can be reused, Gradle short-circuits all work on that project, including the configuration phase and other work such as dependency resolution.

This means that Gradle will only configure and create tooling models for projects whose configuration has changed. This work is done in parallel for each project.

Current limitations

Isolated Projects is a pre-alpha feature, and as such, the current implementation has a number of limitations. These will be addressed in future Gradle releases:

  • Gradle, IntelliJ IDEA, Android Studio, and Kotlin plugins are not yet 100% compatible with Isolated Projects, so you should expect to see some violations reported. The teams are actively working on fixing these incompatibilities.

  • Parallel configuration does not support Configuration on Demand. All projects will be configured, even if they aren’t running tasks.

  • Changes to included builds invalidate all cached results, even when the change would not affect the cached results.

  • The implementation does not exploit the isolation to limit peak memory consumption. Currently, peak memory consumption is a function of how many projects must be configured.

  • All caching, including the configuration cache, is done on the local machine. Remote caching is not supported yet.

How do I use it?

You will need Gradle 8.5 or later to use Isolated Projects, preferably a recent nightly. You should also use the most recent version of IDEA or Android Studio.

The feature is off by default. You can enable it by setting the org.gradle.unsafe.isolated-projects Gradle property to true. For example:

$ gradle build -Dorg.gradle.unsafe.isolated-projects=true

When enabled, Gradle will fail the build whenever build logic attempts to cross project boundaries and access the model of another project. Gradle collects all of these access problems in the configuration cache report, as it does other problems.

The configuration cache command-line options can be used to control how Gradle handles these problems. For example:

  • --configuration-cache-problems=warn can be used to treat access problems as warnings instead of errors.

  • -Dorg.gradle.configuration-cache.max-problems=x can be used to increase the maximum number of problems included in the report.

You can also use -Dorg.gradle.internal.invalidate-coupled-projects=false to force parallel configuration when there are access problems.

Note that these options disable the validation that makes execution parallel- and caching-safe when Isolated Projects is enabled, so you may see some unexpected behavior when using them.