Using Gradle Build Cache to Speed Up Java Builds

Quick answer: enable the build cache to reuse compiled outputs

If your Java project rebuilds the same source files on every CI run or developer machine, turning on Gradle’s build cache can cut build times dramatically by storing and reloading task outputs such as compiled classes and test results.

How the cache works

Gradle treats each task as a function of its inputs. When a task is marked @CacheableTask (or is a built‑in cacheable task like JavaCompile or Test) Gradle computes a hash of all declared inputs. If that hash matches a previous execution, Gradle restores the stored outputs instead of re‑executing the task. The cache can be local (on the developer’s machine) or remote (shared across a team or CI agents).

Worked configuration

Add the following to settings.gradle (or settings.gradle.kts) to enable a local cache and point to a remote cache hosted over HTTPS:

// settings.gradle
buildCache {
    // Local cache – enabled by default in recent Gradle versions
    local {
        enabled = true
        // Optional: limit size to 5 GB and keep 7 days of entries
        maxSize = 5 * 1024 * 1024 * 1024 // 5 GB
        removeUnusedEntriesAfterDays = 7
    }
    // Remote cache – replace with your own endpoint and credentials
    remote {
        enabled = true
        // Example using Gradle Enterprise; you can also use a self‑hosted cache
        url = "https://cache.example.com/gradle"
        // Push credentials – use environment variables or a gradle.properties file
        username = System.getenv("GRADLE_CACHE_USER")
        password = System.getenv("GRADLE_CACHE_PASSWORD")
    }
}

With this in place, run a clean build to prime the cache:

./gradlew clean build --build-cache

On the second invocation (without --clean) you should see messages like:

> Task :compileJava UP-TO-DATE
> Task :test FROM-CACHE

Verification steps

1. Run ./gradlew build --build-cache twice and compare the console output; the second run should report “Cache hit” or “FROM‑CACHE” for cacheable tasks.
2. Inspect the local cache directory: ls ~/.gradle/caches/build-cache-1 (default location). You will see sub‑directories named by cache keys containing compiled class files and test results.
3. If using a remote cache, add --scan to the build command and open the generated build scan; look for “Remote cache hit” in the timeline.

Limits and common mistakes

• Only cacheable tasks benefit. Tasks that read mutable system state (e.g., current timestamp, random numbers) or write to non‑declared outputs will not be cached because their input hash changes each run.
• Non‑deterministic inputs cause misses. If a task’s inputs include absolute file paths that differ between machines, the cache key will differ. Use relative paths or normalize inputs.
• Remote cache security. Never expose the cache endpoint over plain HTTP; credentials can be intercepted. Always use HTTPS and consider token‑based authentication.
• Storage growth. The local cache can consume significant disk space. Set maxSize and a cleanup policy as shown, or run gradle --stop periodically to purge old entries.
• Plugin interference. Some versions of the Android Gradle Plugin override cache settings. After applying the plugin, verify that buildCache.enabled is still true by running ./gradlew properties -q | grep buildCache.

When to avoid the cache

If your build generates code that embeds build timestamps or version numbers directly into the output (e.g., a BuildInfo.java file written by a custom task), the task will never be cache‑able unless you make those values inputs. In such cases, refactor the task to accept the version as a property or disable caching for that specific task with outputs.upToDateWhen { false }.