skip to content

How do you configure the local build cache — change its directory and tune retention — and where does that configuration go?

level: middleimportance: must knowfreq 50%

answer

  1. settings.gradle.kts not build script
  2. buildCache { local { ... } }
  3. directory + removeUnusedEntriesAfterDays
  4. default retention 7 days
  5. enabled / push flags

basics

~10 s

In settings.gradle(.kts) use the buildCache { local { ... } } block. Set directory to relocate it and removeUnusedEntriesAfterDays to control how long unused entries survive (default 7).

solid answer

~40 s

Build cache configuration is a **settings-level** concern, so it goes in `settings.gradle.kts`, not a build script. The `buildCache { local { ... } }` block exposes the local backend. The main knobs are: - `directory` — relocate the cache (default `<gradleUserHome>/caches/build-cache-1`). Useful to put it on a fast disk or a CI-cacheable path. - `removeUnusedEntriesAfterDays` — retention window; entries not read within this many days are eligible for cleanup (default 7). - `enabled` / `push` — whether this backend is used and whether builds write to it. Example: ```kotlin buildCache { local { directory = File(rootDir, ".gradle/build-cache") removeUnusedEntriesAfterDays = 14 } } ``` Note the cache itself must also be turned on (via `org.gradle.caching=true` or `--build-cache`) for any of this to take effect; the block only configures the backend.

code

kotlin · 8 lines
kotlin
// settings.gradle.kts
buildCache {
    local {
        directory = File(rootDir, ".gradle/build-cache")
        removeUnusedEntriesAfterDays = 14
        push = true
    }
}

go deeper

for a junior

Know the block name and the two main properties (directory, retention).

for a middle

Place it in settings, list directory/retention/enabled/push, and note enabling is separate.

for a senior

Reason about retention vs. disk vs. hit-rate trade-offs and relocating the directory for CI snapshotting.

for a principal

Set org-wide conventions (shared init script / convention plugin) for cache location and retention, balancing disk governance against hit rate across many repos.

## Where configuration lives The build cache is configured in **`settings.gradle(.kts)`**, inside a top-level `buildCache { }` block — *not* in `build.gradle(.kts)`. That's because the cache spans the whole build and must be known before projects are configured. Inside `buildCache { }` there are two backend blocks: `local { }` (the on-disk directory) and `remote(HttpBuildCache) { }`. This question is about `local`. ## The local block's properties - **`directory`** — an `Object` resolved as a file path. Defaults to `<Gradle User Home>/caches/build-cache-1`. Relocate it to a fast SSD, a RAM disk, or — common in CI — a path your CI system snapshots between jobs. - **`removeUnusedEntriesAfterDays`** — an `Int`, default `7`. Gradle periodically cleans the cache, deleting entries that haven't been *read* within this many days. A larger value keeps more history (more hits) at the cost of disk; a smaller value bounds disk use. - **`enabled`** — `Boolean`, default `true`. Lets you disable just the local backend while keeping, say, a remote one. - **`push`** — `Boolean`, default `true` for local. When `false`, builds may *read* from the cache but won't *write* new entries. ## Worked example ```kotlin // settings.gradle.kts buildCache { local { directory = File(rootDir, ".gradle/build-cache") removeUnusedEntriesAfterDays = 14 // enabled = true (default) // push = true (default) } } ``` ## It still needs to be switched on Configuring `local { }` does **not** by itself activate caching. The cache as a whole must be enabled — `org.gradle.caching=true` in `gradle.properties` or `--build-cache` on the command line. The block only *describes* the local backend; activation is separate. (Activation mechanics belong to the 'Enabling the Build Cache' topic.) ## Cleanup timing nuance Cleanup is not instantaneous on the day-count boundary; Gradle runs cache cleanup periodically (and can be influenced by Gradle User Home cleanup settings). Treat `removeUnusedEntriesAfterDays` as 'eligible for removal after', not 'deleted at exactly N days'.

  • Why does build cache config live in settings, not the build script?
    The cache spans the whole build and must be configured before projects are evaluated, so it belongs in the settings file.
  • Does setting `removeUnusedEntriesAfterDays` delete entries exactly at that age?
    No — it marks entries eligible for cleanup; Gradle runs cache cleanup periodically, so deletion happens on the next cleanup pass, not precisely at N days.
  • What does `push = false` on the local cache do?
    Builds will read existing entries but won't write new ones to the local cache.

saying these in an interview costs you the question

  • Putting the `buildCache` block in build.gradle instead of settings.gradle.
  • Assuming configuring `local { }` also enables caching — enabling is a separate switch.
  • Believing cleanup happens precisely on the day boundary.

context

resolving links…