skip to content

What do distributionBase, distributionPath, zipStoreBase and zipStorePath control in gradle-wrapper.properties?

level: middleimportance: should knowfreq 40%

answer

  1. Base = root (GRADLE_USER_HOME or PROJECT)
  2. Path = subdir under base
  3. distribution* = unpacked install
  4. zipStore* = downloaded zip
  5. default ~/.gradle/wrapper/dists

basics

~20 s

They decide where the wrapper stores the downloaded distribution. The *Base keys pick a root (usually GRADLE_USER_HOME, sometimes PROJECT), and the *Path keys give a subdirectory under it. 'distribution' is the unpacked Gradle; 'zipStore' is the downloaded zip.

solid answer

~40 s

These four keys control **where the wrapper caches the Gradle distribution** on disk. There are two pairs: `distributionBase`/`distributionPath` locate the **unpacked** Gradle install, and `zipStoreBase`/`zipStorePath` locate the **downloaded zip** archive. Each `*Base` is a symbolic root — either `GRADLE_USER_HOME` (default, `~/.gradle`) or `PROJECT` (the project root). The matching `*Path` is a relative subdirectory under that root, defaulting to `wrapper/dists`. So by default the distribution lands in `~/.gradle/wrapper/dists/`. You'd switch a base to `PROJECT` to keep a fully self-contained, per-project copy (e.g. sandboxed or hermetic CI agents), at the cost of duplicating the download across projects and bloating the workspace. Most teams leave these at defaults and never touch them; they exist for caching-location control, not for selecting the version.

code

properties · 6 lines
properties
# Keep a self-contained per-project Gradle copy
distributionBase=PROJECT
distributionPath=.gradle/dists
zipStoreBase=PROJECT
zipStorePath=.gradle/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

go deeper

for a junior

Know they decide where the downloaded Gradle is cached, defaulting under ~/.gradle.

for a middle

Distinguish the two pairs (unpacked install vs downloaded zip) and the two base roots GRADLE_USER_HOME vs PROJECT.

for a senior

Explain the cache-reuse implications: shared GRADLE_USER_HOME lets many projects share one install; PROJECT base trades reuse for hermeticity.

for a principal

Reason about CI disk strategy across an org — shared caches vs per-project hermetic dirs, and how this interacts with ephemeral build agents.

## The four caching keys Beyond `distributionUrl`, `gradle-wrapper.properties` carries four keys that decide **where on disk** the wrapper puts what it downloads. They come in two pairs: ```properties distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists ``` ### Base vs Path - A `*Base` value is a **symbolic root**, one of: - `GRADLE_USER_HOME` — the Gradle user home, `~/.gradle` by default (overridable via `GRADLE_USER_HOME` env var or `--gradle-user-home`). - `PROJECT` — the root directory of the current build. - A `*Path` value is a **relative subdirectory** appended under that base. ### The two pairs - **`distributionBase` + `distributionPath`** → where the **unpacked** Gradle distribution (the runnable install) is placed. - **`zipStoreBase` + `zipStorePath`** → where the **downloaded `.zip`** is stored before/after unpacking. With defaults, both resolve to `~/.gradle/wrapper/dists/`, so the zip and its exploded form sit side by side, keyed by a hash derived from the `distributionUrl`. This shared location is why multiple projects on the same machine reuse one cached Gradle install per version. ## When you'd change them Switching a base to `PROJECT` makes the distribution **self-contained inside the workspace** — useful for fully hermetic/sandboxed CI agents, air-gapped reproductions, or where the shared user home isn't writable. The trade-off: each project re-downloads and stores its own copy, wasting disk and time, and it bloats the checkout. In practice you almost never edit these; they are about **cache placement**, not version selection or integrity. ## Mental model Think of `distributionUrl` as *which* Gradle, and these four as *where to keep it*. They have no effect on build behaviour, only on disk layout and reuse.

  • What are the two legal values for a *Base key and what do they mean?
    GRADLE_USER_HOME (the ~/.gradle user home, the default) and PROJECT (the build's root directory).
  • Why might you set the bases to PROJECT, and what's the downside?
    To make the Gradle install self-contained inside the workspace (hermetic/sandboxed CI). Downside: each project re-downloads its own copy, wasting disk and time.

saying these in an interview costs you the question

  • Confusing distributionPath with the project build cache or dependency cache — these are only the wrapper's Gradle distribution.
  • Thinking these keys affect which Gradle version runs (they don't; distributionUrl does).
  • Assuming *Path is absolute — it's always relative to the resolved *Base.

context

resolving links…