How do you upgrade the Gradle version used by a project that has the wrapper checked in?
answer
- `./gradlew wrapper --gradle-version X`
- edits distributionUrl in gradle-wrapper.properties
- never hand-install Gradle
- two passes: bump URL, then regenerate jar
- commit all wrapper files
basics
~10 sRun ./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 sYou 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# 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.7go deeper
Know the command ./gradlew wrapper --gradle-version X and that it changes distributionUrl so nobody has to install Gradle.
Explain the two-pass procedure and which wrapper files exist; mention --distribution-type all and committing all files.
Frame it as a self-hosting upgrade and connect to reproducibility/CI parity; mention verifying with --version and the distribution checksum.
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.