skip to content

Why might you relocate the local build cache directory, and what should you watch out for when you do?

level: seniorimportance: should knowfreq 28%

answer

  1. directory = File(rootDir, ...)
  2. SSD/RAM disk for speed
  3. project-relative for CI snapshot
  4. network FS can be net-negative
  5. gitignore project-local cache

basics

~20 s

Set local { directory = ... } to move the cache — e.g. onto a fast SSD, a project-local path, or a CI path you can snapshot. Watch that the path is writable, fast, and that sharing it across users/agents stays consistent.

solid answer

~50 s

By default the local cache sits in Gradle User Home (`~/.gradle/caches/build-cache-1`). You relocate it via `buildCache { local { directory = ... } }` for a few reasons: - **Faster storage** — point it at an SSD/NVMe or RAM disk to speed pack/unpack. - **CI snapshotting** — a project-relative path (e.g. `${rootDir}/.gradle/build-cache`) lets CI cache/restore the directory between jobs as a build artifact. - **Disk governance** — move it off a small system partition. Watch-outs: the path must be writable by every process that builds; sharing one local directory across concurrent builds/agents is supported but they all read/write the same files, so put it on reliable storage; a network filesystem can be *slower* than re-running cheap tasks; and if you make it project-relative remember to gitignore it. Relocating doesn't change correctness — keys are content hashes — only performance and lifecycle.

code

kotlin · 8 lines
kotlin
// settings.gradle.kts — project-relative cache, snapshot-friendly in CI
buildCache {
    local {
        directory = File(rootDir, ".gradle/build-cache")
        removeUnusedEntriesAfterDays = 7
    }
}
// remember: add .gradle/build-cache/ to .gitignore

go deeper

for a junior

Know you can set directory to move the cache off the default path.

for a middle

Give concrete reasons (speed, CI, disk) and set it in settings with the right syntax.

for a senior

Weigh storage latency, concurrency, gitignore, and that correctness is unaffected; benchmark network FS.

for a principal

Standardize cache placement across teams/CI, deciding ephemeral-local-plus-remote vs. snapshotted local-directory strategies and their cost/governance implications.

## Default vs. relocated The local cache defaults to `<Gradle User Home>/caches/build-cache-1`, shared across all of that user's projects. You override the location with: ```kotlin // settings.gradle.kts buildCache { local { directory = File(rootDir, ".gradle/build-cache") } } ``` `directory` accepts anything resolvable to a path (a `File`, a path string). ## Why relocate 1. **Performance** — the cache constantly packs outputs into archives and unpacks them on hits. Faster storage (SSD/NVMe, tmpfs/RAM disk) reduces that overhead. A slow or network disk can make caching *net-negative* for cheap tasks. 2. **CI artifact caching** — CI systems can persist a path between jobs (e.g. `actions/cache`, GitLab cache). Pointing the Gradle cache at a project-relative directory lets the CI cache mechanism snapshot it, so the next job warms up with previous outputs. (Seeding strategy details belong to the CI seeding topic; here the point is *where* the directory lives.) 3. **Disk governance** — keep the cache off a small `$HOME`/system partition. ## What to watch for - **Writability & permissions** — every process building must be able to read and write the directory. Shared-agent setups need consistent ownership. - **Concurrent access** — multiple builds can safely share one local directory; Gradle coordinates access. But they contend on the same files, so use reliable storage. - **Network filesystems** — NFS/SMB latency can exceed the cost of just re-running fast tasks; benchmark before committing. - **Gitignore** — a project-relative cache must not be committed. Add it to `.gitignore`. - **Format version** — the directory still uses the `build-cache-1` format; mixing Gradle versions with incompatible formats is handled by the version suffix, not by your path choice. ## What relocating does NOT change Correctness. Cache keys are content hashes of inputs; moving the directory changes only *where* entries live and *how fast* they're accessed, never *whether* a hit is valid. If outputs become wrong after relocation, the problem is task input/output declarations, not the directory.

  • Could relocating the cache onto a network drive hurt performance?
    Yes. Pack/unpack over a high-latency network filesystem can cost more than simply re-executing cheap tasks; benchmark before adopting it.
  • Does moving the directory affect cache correctness?
    No. Keys are content hashes of inputs; the directory only changes location and access speed, never whether a hit is valid.
  • Is it safe for several builds to share one local cache directory?
    Yes, Gradle coordinates concurrent access to the local cache directory; just keep it on reliable storage since they contend on the same files.

saying these in an interview costs you the question

  • Assuming a network/shared mount is automatically faster — it can be slower than re-running tasks.
  • Forgetting to gitignore a project-relative cache directory.
  • Believing relocation can cause stale/incorrect outputs — that's an input-declaration problem, not a location one.

context

resolving links…