Enabling Gradle Configuration Cache for Faster Build Startup

Desired outcome

Reduce configuration-phase time by caching the result of Gradle's configuration phase and reusing it across builds when inputs have not changed. On a typical multi-module project, this cuts several seconds off each build invocation after the first cache population.

Prerequisites

• Gradle 7.5 or later (8.x recommended for stability and plugin compatibility).
• All applied plugins must declare configuration-cache compatibility. Check each plugin's release notes or documentation.
• Build logic must avoid deprecated APIs that capture mutable state during configuration (for example, project.afterEvaluate used to mutate project properties).
• No non-deterministic behavior during configuration: no reading system clocks, random values, or environment variables that differ between invocations.

Procedure

1. Test compatibility

Run the following from the project root (where gradlew is executable). This performs a dry-run and fails fast with diagnostics if incompatibilities exist.

./gradlew --configuration-cache help

Expected result on a compatible build: Configuration cache entry stored. If it fails, Gradle prints a report listing each problem with file and line references.

2. Fix reported issues

Common fixes include:

• Replace direct property access (project.version) with the Provider API: project.provider { project.version } or project.versionProperty().
• Avoid iterating FileCollection or Configuration at configuration time; defer to task actions using lazy APIs.
• Use tasks.register("name") instead of tasks.create("name") so task creation is deferred.
• Migrate legacy apply plugin: 'java' in subprojects to the plugins {} block in the root or convention plugins.

3. Enable the cache persistently

Add the flag to gradle.properties in the project root:

org.gradle.configuration-cache=true

This ensures every invocation uses the cache without requiring the command-line flag.

4. Populate the cache

Run a clean build to create the initial cache entry:

./gradlew clean build

Output should include Configuration cache entry stored near the end.

5. Verify reuse on subsequent builds

Run the same command again without changes:

./gradlew build

Output should show Reusing configuration cache and the configuration phase should be near-zero in the timeline.

Expected checks

• Build scan: Add --scan to any command. In the scan UI, open the "Configuration cache" section; it reports reuse rate and lists any problems.
• Profile report: Run ./gradlew build --profile and open build/reports/profile/profile-.html. Compare "Configuration" phase duration before and after enablement.
• Properties check: Confirm gradle.properties contains only org.gradle.configuration-cache=true and no conflicting flags like org.gradle.configuration-cache.problems=warn (unless intentionally debugging).

Recovery options

Common incompatibility patterns

Plugin ecosystem notes

Major plugins (Android Gradle Plugin 7.2+, Spring Boot 2.7+, Kotlin 1.7+, Java, Groovy, Scala) are compatible. Third-party plugins vary: check their changelogs for "configuration cache support". An incompatible plugin blocks the cache for the entire build — upgrade the plugin or file an issue with its maintainer.

CI/CD integration

Cache the directory ~/.gradle/configuration-cache between pipeline runs (e.g., GitHub Actions actions/cache, GitLab CI cache key). Combine with the Gradle Build Cache (org.gradle.caching=true) for artifact reuse. Ensure the CI image uses the same Gradle version and JDK as developers; any mismatch causes a cache miss on first run.

Limitations and cautions

• Benefits diminish for small projects (under ~10 modules) or highly dynamic builds where inputs change every invocation.
• First enablement often surfaces latent bugs: non-deterministic configuration, mutable state leakage, or reliance on execution-time APIs during configuration.
• IntelliJ IDEA's Gradle sync (as of 2024.3) does not fully leverage the configuration cache; sync times may not improve.
• Changing Gradle version, JDK, or any plugin version invalidates the cache — expect a cache miss on the first build after upgrades.
• Mixing compatible and incompatible plugins in the same build makes the whole build ineligible; migrate or isolate incompatible plugins in a separate composite build.

Verification checklist

1. Run ./gradlew help --configuration-cache --scan and confirm the build scan shows "Configuration cache reused: true" on the second run.
2. Compare configuration-phase duration in the build scan timeline before and after enablement.
3. Verify gradle.properties contains org.gradle.configuration-cache=true and no conflicting flags.
4. Run ./gradlew --configuration-cache-problems=warn clean build to surface any remaining warnings without failing.
5. Modify a build script (e.g., add a comment) and confirm the next run shows a cache miss and "Configuration cache entry stored".
6. In CI, cache ~/.gradle/configuration-cache and measure restore + build time across several runs.