Cutting Android Gradle Configuration Time with the Configuration Cache

The problem: configuration dominates every build

On a modular Android project the Gradle configuration phase can take 10–30 seconds before any task even starts. That cost repeats on every clean build, every CI run, and every time a developer hits Sync Project with Gradle Files. The Configuration Cache, stable since Gradle 8.1 and fully supported by Android Gradle Plugin 8.1+, stores the result of that phase and re‑uses it when the inputs (build scripts, plugins, gradle.properties) have not changed.

Enable the cache in three steps

1. Upgrade tooling – Ensure gradle-wrapper.properties points to Gradle 8.1+ and build.gradle.kts (or build.gradle) uses com.android.application / com.android.library plugin version 8.1+.
2. Add the flags to gradle.properties (project root):

   org.gradle.configuration-cache=true
   org.gradle.unsafe.configuration-cache-problems=warn

   The warn flag lets the build succeed while Gradle reports every cache‑incompatibility as a warning. Treat it as a temporary migration aid only.
3. Run a dry‑run diagnostic from the project root (requires execute permission on the wrapper):

   ./gradlew help --configuration-cache --dry-run

   The output lists each problem with a code (e.g. PROJECT_AFTER_EVALUATE, TASK_READS_FILE_AT_CONFIGURATION) and the exact script location. Fix each item, then remove the warn flag.

Typical migration blockers and how to fix them

• project.afterEvaluate usage – Replace with lazy task configuration or the tasks.named(...).configure { … } API.
• Mutable project state during configuration – Move any logic that writes to project.ext or modifies project.version into a task action.
• Legacy plugin application (apply plugin: 'com.android.application') – Switch to the plugins DSL: id('com.android.application') version '8.3.0' apply false in the root settings.gradle.kts and plugins { id('com.android.application') } in each module.
• Tasks reading files at configuration time – Defer file reads to doFirst / doLast or use provider { file(...).readText() }.

Kotlin DSL (.gradle.kts) migrates more cleanly because the type‑safe API avoids dynamic property access that breaks cacheability.

Worked example: a 40‑module Compose/Kotlin app

Before enabling the cache the Configure project phase reported ~22 s on a clean build. After fixing the warnings and dropping the warn flag the same phase dropped to ~1.3 s. Incremental source‑change builds improved roughly 35 % because the configuration step is skipped entirely on a cache hit.

In Android Studio the Build tool window shows a lightning‑bolt icon next to the build timestamp when the configuration cache is reused. That visual cue lets developers confirm the cache is active without leaving the IDE.

Trade‑offs and limitations

• Third‑party plugin compatibility – Older Firebase Crashlytics, Realm, or internal enterprise plugins often lack support. Verify each plugin’s release notes before enabling.
• File‑system watching – On Linux and Windows you must enable Gradle’s --watch-fs (or set org.gradle.vfs.watch=true) for reliable invalidation; macOS uses native FSEvents automatically.
• Hidden problems in warn mode – The cache is still written while warnings are emitted. A stale cache can produce incorrect builds. Remove warn as soon as the report is clean.
• CI caching – Ephemeral agents (GitHub Actions, Bitrise) benefit when the Gradle user home (~/.gradle) is cached across workflow steps; typical pipeline time drops 20–40 %.

Actionable closing: verify and ship

1. Run ./gradlew help --configuration-cache --dry-run on a clean checkout. Confirm zero warnings.
2. Remove org.gradle.unsafe.configuration-cache-problems=warn from gradle.properties.
3. Trigger a clean build locally and in CI. In Android Studio watch for the lightning‑bolt icon; in CI compare the Configure project duration in Gradle Build Scans (enable with buildScan { publishAlways() }) before and after.
4. Introduce a deliberate input change (e.g., bump a version in gradle.properties) and verify the next build re‑runs configuration (no lightning bolt) and the following build re‑uses the cache again.

Once the verification steps pass, the configuration cache becomes a low‑maintenance speed win for every developer and every pipeline run.