skip to content

What is org.gradle.configureondemand, when does it help, and why is it rarely needed now?

level: seniorimportance: should knowfreq 30%

answer

  1. configure only needed projects
  2. needs decoupled projects
  3. helps big multi-project builds
  4. superseded by configuration cache
  5. --configure-on-demand

basics

~10 s

org.gradle.configureondemand=true tells Gradle to configure only the projects relevant to the requested tasks instead of every project. It helped large decoupled multi-project builds, but the configuration cache largely supersedes it.

solid answer

~40 s

`org.gradle.configureondemand=true` enables **configuration-on-demand**: instead of configuring *every* project in a multi-project build, Gradle configures only the root and the subprojects actually needed to satisfy the requested tasks (plus their dependencies). The win is reduced configuration time in large builds where you usually invoke a task in just a few modules. It requires **decoupled projects**, because skipping configuration of a project is unsafe if other projects reach into it during configuration. In modern Gradle this is rarely the right lever: the **configuration cache** caches the whole configuration result and parallelizes it, giving bigger and safer wins, so teams generally adopt the configuration cache instead. You enable it with the property or `--configure-on-demand`.

code

properties · 1 line
properties
org.gradle.configureondemand=true

go deeper

for a junior

Know it configures only the projects needed for the requested tasks.

for a middle

Explain when it helps (large multi-project builds) and that it needs decoupled projects.

for a senior

Articulate why the configuration cache supersedes it and the trade-offs / limitations.

for a principal

Advise teams to invest in configuration-cache compatibility rather than configure-on-demand, treating the latter as legacy.

## The problem it targets By default Gradle configures **all** projects in a build before executing anything, even if you only asked for `:app:assemble`. In a 200-module build that fixed configuration cost is paid every invocation. ## What configure-on-demand does With `org.gradle.configureondemand=true`, Gradle evaluates which projects are actually required for the requested tasks (the target projects and the projects they depend on) and configures only those, leaving the rest unconfigured. For builds where developers typically touch a small slice of modules, this trims wasted configuration work. ## The decoupling requirement Configure-on-demand assumes **decoupled projects** — a project must not, during configuration, reach into another project that might be skipped. If project A configures itself by reading project B's tasks or extensions and B is not configured, results are wrong or the build fails. This is the same decoupling discipline that `org.gradle.parallel` and the configuration cache demand. ## Why it is largely obsolete The **configuration cache** (`org.gradle.configuration-cache`) caches the *entire* configuration phase and reuses it across builds, and also configures projects in parallel. That delivers a larger, more reliable speedup than selectively skipping projects, and it works for the common case of repeated builds. As a result, Gradle documentation positions the configuration cache as the modern replacement, and configure-on-demand is a niche, incubating-style option that most builds should not need. It also has known limitations with certain cross-project dependency patterns. ```properties # Legacy lever; prefer configuration-cache instead org.gradle.configureondemand=true ``` ## When you might still reach for it Only if you cannot yet adopt the configuration cache (e.g. plugins incompatible with it) but still suffer from configuration time in a large, well-decoupled build. Even then, fixing the configuration-cache incompatibilities is usually the better long-term move. ## Enabling - Persistent: `org.gradle.configureondemand=true`. - Per build: `--configure-on-demand`.

  • Why does configure-on-demand require decoupled projects?
    It skips configuring projects not needed by the requested tasks. If another project reaches into a skipped project's state during configuration, the build sees incomplete or wrong configuration, so projects must not couple at configuration time.
  • Why do most teams prefer the configuration cache over configure-on-demand today?
    The configuration cache caches and reuses the entire configuration phase across builds and parallelizes it, giving larger and safer speedups than selectively skipping projects, and it covers the common repeated-build case.

saying these in an interview costs you the question

  • Presenting it as the primary modern way to speed up configuration — that is the configuration cache.
  • Ignoring the decoupled-projects requirement.
  • Confusing it with the build cache or parallel execution.

context

resolving links…