skip to content

Upgrading Gradle Versions

4 roadmaps5 questions

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.

on this pageshow

explore

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 these in an interview costs you the question

  • 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

resolving links…

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