skip to content

What do the `--distribution-type` and `--gradle-distribution-url` options on the wrapper task do during an upgrade?

level: middleimportance: nice to knowfreq 20%

answer

  1. bin = binaries only (default)
  2. all = + sources/docs for IDE assist
  3. --gradle-distribution-url = mirror/custom URL
  4. --gradle-distribution-sha256-sum = integrity
  5. flags shape distributionUrl, not the procedure

basics

~10 s

--distribution-type bin|all chooses between the binary-only zip and the full (sources + docs) zip written into distributionUrl. --gradle-distribution-url lets you point at a custom/mirror URL instead of resolving from a version number.

solid answer

~30 s

Beyond `--gradle-version`, the `wrapper` task takes options that shape the resulting `distributionUrl`. `--distribution-type` selects `bin` (binaries only — smaller, the default) or `all` (binaries plus sources and documentation, which IDEs use for richer code assistance). `--gradle-distribution-url` lets you set an explicit URL — useful when you mirror Gradle internally or pull from a corporate artifact proxy instead of services.gradle.org. There's also `--gradle-distribution-sha256-sum` to bake in `distributionSha256Sum` for integrity, and `--network-timeout`. During an upgrade you'd typically combine `--gradle-version X --distribution-type all` so developers get sources, or `--gradle-distribution-url <mirror>` in locked-down networks. All of these still flow through the same two-pass procedure.

code

bash · 7 lines
bash
# Full distribution for richer IDE support
./gradlew wrapper --gradle-version 8.7 --distribution-type all

# Pin to an internal mirror with checksum
./gradlew wrapper \
  --gradle-distribution-url https://nexus.internal/repo/gradle-8.7-bin.zip \
  --gradle-distribution-sha256-sum 544c35d6bd849ae8a5ed0bcea39ba677dc40f49df7d1835561582da2009b961d

go deeper

for a junior

Awareness that --distribution-type all exists is plenty.

for a middle

Explain bin vs all and the mirror/custom-URL use case.

for a senior

Connect --gradle-distribution-url + checksum to air-gapped/mirror governance and integrity.

for a principal

Set org policy: mandated mirror URL + checksum for all repos, and whether all is standardized for developer experience.

## The wrapper task is configurable The built-in `wrapper` task exposes options that decide exactly what `distributionUrl` (and friends) end up in `gradle-wrapper.properties`. ### `--distribution-type bin | all` - `bin` — binaries only. Smallest download; the common default. - `all` — binaries **plus sources and documentation**. IDEs (IntelliJ) use the sources to give you navigation and Javadoc into Gradle's own API when editing build scripts. Many teams prefer `all` for the better authoring experience at the cost of a larger download. ```bash ./gradlew wrapper --gradle-version 8.7 --distribution-type all # -> distributionUrl=...gradle-8.7-all.zip (note '-all' vs '-bin') ``` ### `--gradle-distribution-url <url>` Sets an explicit distribution URL rather than letting Gradle build one from the version number. Essential when: - you host Gradle on an internal mirror / artifact proxy (air-gapped or policy-restricted networks), - you need a non-standard distribution location. ```bash ./gradlew wrapper --gradle-distribution-url \ https://nexus.internal/repository/gradle/gradle-8.7-bin.zip ``` ### `--gradle-distribution-sha256-sum <hash>` Writes `distributionSha256Sum` so the wrapper verifies the download — pairs naturally with a mirror URL for supply-chain safety. ### `--network-timeout <ms>` Raises the download timeout for slow links. ## They don't change the procedure These flags only shape *what* gets pinned. You still apply the same two-pass upgrade (bump, build to surface deprecations, regenerate jar/scripts) and commit all wrapper files.

  • When would you choose `all` over `bin`?
    When you want IDE navigation and Javadoc into Gradle's own API while authoring build scripts; `all` bundles sources and docs at the cost of a larger download.
  • Why might a company set `--gradle-distribution-url` to an internal host?
    Air-gapped or policy-restricted networks can't reach services.gradle.org, so they mirror the distribution on an internal artifact proxy and point the wrapper there.

saying these in an interview costs you the question

  • Claiming `all` vs `bin` changes Gradle's behavior or features — it only adds sources/docs to the download.
  • Thinking these flags replace the two-pass procedure.

context

resolving links…