skip to content

Where does Gradle's local build cache store its entries by default, and what does it actually hold?

level: juniorimportance: must knowfreq 55%

answer

  1. ~/.gradle/caches/build-cache-1
  2. Gradle User Home dir
  3. content-addressed task-output archives
  4. shared across user's projects
  5. FROM-CACHE restore

basics

~10 s

By default the local build cache lives in ~/.gradle/caches/build-cache-1. It stores the outputs of cacheable tasks keyed by a hash, so a later build can reuse them instead of re-running the task.

solid answer

~40 s

The local build cache is a directory on the same machine — by default `<gradleUserHome>/caches/build-cache-1`, i.e. `~/.gradle/caches/build-cache-1`. Each entry is a content-addressed archive (a zip-like file) of a cacheable task's outputs, named by the task's **build cache key** (a hash of all its inputs). When a task runs with the same key again — even in a different project or after a `clean` — Gradle loads the archived outputs from this directory instead of executing the task. Because it lives in Gradle User Home, the cache is shared across every project built by that user on the machine, which is what makes it useful for repeated `clean build` cycles and switching branches. It is per-user and per-machine, distinct from a shared remote cache.

code

bash · 3 lines
bash
# Default local cache location
ls ~/.gradle/caches/build-cache-1
# entries are hash-named archive files, one per cached task output set

go deeper

for a junior

Name the default path and that it stores reusable task outputs keyed by a hash.

for a middle

Explain it's in Gradle User Home, shared across the user's projects, and contrast it with up-to-date checking.

for a senior

Discuss the content-addressed format, why it survives clean/branch switches, and how to relocate directory.

for a principal

Frame local cache as one tier of a caching strategy (local + remote), and when relocating/wiping it matters for build determinism and disk governance.

## What the local build cache is The **build cache** reuses the *outputs* of tasks across builds. It is different from incremental builds / up-to-date checks: up-to-date checking only reuses outputs that are still sitting in the current project's build directory, whereas the cache can restore outputs even after `clean`, on a fresh checkout, or in a sibling project — as long as the inputs match. The **local** build cache is one of two cache backends (the other is a remote/HTTP cache). It is simply a directory on the local filesystem. ## Location By default the directory is: ``` <Gradle User Home>/caches/build-cache-1 ``` Gradle User Home defaults to `~/.gradle`, so the path is usually `~/.gradle/caches/build-cache-1`. The `build-cache-1` suffix is a format version — if Gradle changes the on-disk format it bumps the number, so old and new caches don't collide. Because the directory lives in Gradle User Home, it is **shared across all projects** that user builds on the machine. That's deliberate: identical compilation across two checkouts of the same repo, or across feature branches, can hit the same entries. ## What an entry contains Each entry is a **content-addressed** packed archive of one task's declared outputs. The file name is the task's **build cache key** — a hash computed from every declared input (input files' content, input properties, the task's implementation classpath, etc.). On a cache hit Gradle unpacks the archive into the task's output locations and marks the task `FROM-CACHE`. ## Configuring it Local cache settings live in the `buildCache { local { ... } }` block in `settings.gradle(.kts)`: ```kotlin buildCache { local { directory = File(rootDir, ".gradle/build-cache") removeUnusedEntriesAfterDays = 7 } } ``` You can point `directory` somewhere else (e.g. a fast SSD or a path you can wipe in CI), and tune retention with `removeUnusedEntriesAfterDays`. ## Key takeaways - Default path: `~/.gradle/caches/build-cache-1`. - Per-user, per-machine, shared across that user's projects. - Entries are hash-keyed archives of cacheable task outputs. - Distinct from up-to-date checking and from the remote cache.

  • How is the local cache different from up-to-date checking?
    Up-to-date checking only reuses outputs still present in the current project's build dir; the cache restores outputs from an archive even after `clean` or on a fresh checkout, keyed by input hash.
  • Is the local cache shared between different projects?
    Yes — it lives in Gradle User Home, so every project that user builds on the machine reads and writes the same `build-cache-1` directory.

saying these in an interview costs you the question

  • Claiming the cache lives in each project's `build/` directory — that's the output dir, not the cache.
  • Confusing the build cache with the dependency/module cache (`modules-2`).

context

resolving links…