skip to content

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…