skip to content

Upgrading Gradle Versions

The two-pass wrapper upgrade: bump the distribution, fix deprecations with warnings turned on, then regenerate the scripts and jar. Interviewers ask because a single-pass upgrade leaves the wrapper itself behind.

part ofGradleread it →
on this pageshow

questions

5

How do you upgrade the Gradle version used by a project that has the wrapper checked in?

level: juniorimportance: must knowfreq 70%

answer

  1. `./gradlew wrapper --gradle-version X`
  2. edits distributionUrl in gradle-wrapper.properties
  3. never hand-install Gradle
  4. two passes: bump URL, then regenerate jar
  5. commit all wrapper files

basics

~10 s

Run ./gradlew wrapper --gradle-version X. This rewrites distributionUrl in gradle-wrapper.properties so the next ./gradlew invocation downloads and uses that version. You never hand-install Gradle.

solid answer

~40 s

You drive the upgrade through the wrapper itself, never by installing Gradle locally. Run `./gradlew wrapper --gradle-version 8.7` (optionally `--distribution-type all` to get sources/docs). That task edits `gradle/wrapper/gradle-wrapper.properties`, changing the `distributionUrl` to point at the requested version. The wrapper jar and `gradlew`/`gradlew.bat` scripts aren't necessarily rewritten on this first run — they're produced by whatever Gradle version is *currently* running. So the canonical practice is a two-pass upgrade: first pass bumps the `distributionUrl`; then you actually run a build with the new version (so it downloads), and re-run `./gradlew wrapper` so the *new* Gradle regenerates the wrapper jar and scripts to match. Commit all wrapper files so every developer and CI gets the identical version with no manual setup.

code

bash · 7 lines
bash
# Pass 1: bump the distributionUrl
./gradlew wrapper --gradle-version 8.7 --distribution-type all

# Pass 2: run with new version, then regenerate wrapper jar/scripts
./gradlew wrapper --gradle-version 8.7

./gradlew --version   # confirms 8.7

go deeper

for a junior

Know the command ./gradlew wrapper --gradle-version X and that it changes distributionUrl so nobody has to install Gradle.

for a middle

Explain the two-pass procedure and which wrapper files exist; mention --distribution-type all and committing all files.

for a senior

Frame it as a self-hosting upgrade and connect to reproducibility/CI parity; mention verifying with --version and the distribution checksum.

for a principal

Treat wrapper version as a governed artifact: standardized upgrade cadence, automation (Dependabot/renovate), and checksum verification across the org's repos.

## What the wrapper is The Gradle Wrapper is a small set of files committed to your repo that lets anyone build the project with the exact Gradle version it expects, without installing Gradle. The files are: - `gradlew` / `gradlew.bat` — launcher scripts - `gradle/wrapper/gradle-wrapper.jar` — the bootstrapping jar that downloads + caches the distribution - `gradle/wrapper/gradle-wrapper.properties` — declares **which** distribution, via `distributionUrl` When you run `./gradlew build`, the jar reads `distributionUrl`, downloads that distribution into `~/.gradle/wrapper/dists` (if not cached), and delegates to it. ## The upgrade command The built-in `wrapper` task performs the upgrade: ```bash ./gradlew wrapper --gradle-version 8.7 ``` This edits `gradle-wrapper.properties` so `distributionUrl` references `gradle-8.7-bin.zip`. Useful flags: - `--distribution-type all` — pulls the full distribution (includes sources + docs, better IDE assistance) instead of `bin`. - `--gradle-version latest` — resolves to the newest stable release. - `--network-timeout` — for slow mirrors. ## Why one command isn't enough — the two-pass rule The `wrapper` task runs under the *currently active* Gradle. On the first run it updates the URL but the regenerated `gradle-wrapper.jar` and scripts are still produced by the **old** version. To get wrapper files that genuinely match the target version you must: 1. Run `./gradlew wrapper --gradle-version X` (bumps the URL). 2. Run a real build / `./gradlew wrapper` again so the **new** Gradle downloads and regenerates the jar + scripts to its own format. That second pass is what makes the wrapper "self-hosting" at the new version. Commit every wrapper file together. ## Verifying ```bash ./gradlew --version ``` should now report the target version, downloaded transparently on first use.

  • Which file actually pins the version, and what changes in it?
    `gradle/wrapper/gradle-wrapper.properties` — the `distributionUrl` line changes to point at the target distribution zip (e.g. `gradle-8.7-bin.zip`).
  • Do you need Gradle installed on your machine to run the upgrade?
    No. You invoke `./gradlew`, which uses the wrapper jar already in the repo; the upgrade and all builds run through the wrapper.

It's like a self-updating installer baked into the repo: you tell it which version, it fetches and runs that version for everyone, so no one has to install anything by hand.

  • Saying you upgrade by downloading/installing a new Gradle SDK and editing PATH — defeats the wrapper's purpose.
  • Hand-editing the version number with no mention that the jar/scripts also need regenerating.

context

open as a page

Walk through the two-pass Gradle upgrade procedure and explain why each pass matters.

level: middleimportance: must knowfreq 55%

basics

~10 s

Pass 1: ./gradlew wrapper --gradle-version X bumps distributionUrl. Then build with --warning-mode=all and fix deprecations. Pass 2: re-run ./gradlew wrapper so the new Gradle regenerates gradlew/jar to match itself.

open as a page

After upgrading, which wrapper files must be committed and why does committing them matter for the team?

level: middleimportance: should knowfreq 45%

basics

~10 s

Commit all four: gradle-wrapper.properties, gradle-wrapper.jar, gradlew, and gradlew.bat. Together they guarantee every developer and CI run uses the exact same Gradle version with zero manual install.

open as a page

How would you plan and roll out a Gradle major-version upgrade across many repositories in an organization while keeping CI safe?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Step through minors first, fixing deprecations with --warning-mode=all each hop, then take the major. Pin via the wrapper, verify on a branch in CI, automate the bump with renovate/Dependabot, and verify the distribution checksum.

open as a page

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

level: middleimportance: nice to knowfreq 20%

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.

open as a page