skip to content

How does Project Isolation build on and differ from the configuration cache?

level: seniorimportance: should knowfreq 24%

answer

  1. Config cache = whole build, one unit
  2. Project Isolation = per-project unit
  3. Parallel configuration across projects
  4. Incremental: only changed project reconfigured
  5. Isolation implicitly enables config cache

basics

~20 s

The configuration cache stores the whole configuration phase result and reuses it when inputs are unchanged. Project Isolation extends that to a per-project granularity, so projects configure in parallel and only changed projects are reconfigured.

solid answer

~50 s

The **configuration cache** captures the outcome of the configuration phase (the task graph and configured state) keyed by its inputs; on a cache hit Gradle skips configuration entirely and goes straight to execution. It treats the build as one unit. **Project Isolation** takes the same caching/state-capture model and makes the **project the unit of caching and parallelism**. Because each project's configuration is isolated from the others, Gradle can configure projects on separate threads and cache each one independently — so editing one project invalidates only that project (and its dependents), not the whole build, giving **incremental configuration**. Project Isolation builds on the configuration cache and enables it implicitly. The difference is granularity and parallelism: the configuration cache is all-or-nothing for the build; Project Isolation makes it fine-grained and parallel by enforcing the isolation that makes per-project independence sound.

code

toml · 5 lines
toml
# Configuration cache only:
org.gradle.configuration-cache=true

# Project Isolation (implies configuration cache):
org.gradle.unsafe.isolated-projects=true

go deeper

for a junior

Know the configuration cache skips re-running configuration; Project Isolation is a finer, per-project version.

for a middle

Explain the two-phase model and that isolation changes the caching granularity to per-project.

for a senior

Contrast whole-build vs per-project caching, parallel + incremental configuration, and the implicit dependency between the two.

for a principal

Reason about adoption ROI: isolation's parallel/incremental configuration matters most at scale, and the config cache is the migration stepping stone.

## Configuration cache recap Gradle runs in two phases: **configuration** (evaluate settings + build scripts, build the task graph) and **execution** (run tasks). The **configuration cache** serializes the result of the configuration phase, keyed by inputs such as build scripts, `gradle.properties`, environment variables, system properties, and the requested tasks. On a subsequent run with the same inputs, Gradle **loads the cached configuration and skips the configuration phase**, jumping to execution. To make this sound, scripts must not read undeclared inputs at execution time and tasks must capture only serializable state — hence rules around not referencing `Project` at execution time and using `Provider`/`Property` for lazy values. ## Where Project Isolation extends it The plain configuration cache treats the **whole build** as one cached unit: change any input and the whole configuration is re-run (though much can be reused). **Project Isolation** changes the *granularity*. By forbidding cross-project access at configuration time, it makes each project's configuration provably independent of its siblings. That independence lets Gradle: - **Configure projects in parallel**, each on its own thread. - **Cache each project's configuration separately**, so a change to one project's script invalidates and reconfigures only that project (plus dependents) — **incremental configuration**. ## Summary of the relationship | Aspect | Configuration cache | Project Isolation | |---|---|---| | Unit of caching | Whole build | Per project | | Configuration parallelism | No (single config phase) | Yes (projects in parallel) | | Incremental on edit | Coarse | Fine — only changed projects | | Enables the other? | Standalone | Builds on + implicitly enables config cache | | Maturity | Stable/GA-ish | Incubating (`unsafe` flag) | ## Practical implication If you've already adopted the configuration cache, your build is most of the way to Project Isolation: the remaining work is removing cross-project access so each project can be cached and configured in isolation. The payoff scales with project count — large multi-project builds benefit most from parallel, incremental configuration.

  • Why does Project Isolation give incremental configuration while the plain configuration cache does not?
    Because isolation makes each project's configuration independent, Gradle can key the cache per project. An edit invalidates only that project (and dependents). Without isolation, projects can couple, so the safe unit of caching is the whole build.
  • If a build already works with the configuration cache, what's left to enable Project Isolation?
    Removing remaining cross-project configuration access — sibling task/extension mutation, allprojects/subprojects mutation, eager cross-project reads — so each project can be configured and cached in isolation.

saying these in an interview costs you the question

  • Saying the configuration cache already configures projects in parallel (it doesn't — that's what isolation adds).
  • Treating them as unrelated features rather than isolation building on the cache.

context

resolving links…