How do you upgrade the Gradle version used by a project's wrapper, and what command actually regenerates the wrapper files?
answer
- ./gradlew wrapper --gradle-version
- rewrites distributionUrl
- run with current wrapper, then commit
- run twice to regenerate scripts/jar
- latest vs exact pin
basics
~10 sRun ./gradlew wrapper --gradle-version 9.0. The built-in wrapper task rewrites gradle-wrapper.properties (and scripts/jar) to point at the requested version, so everyone uses it on the next build.
solid answer
~40 sGradle ships a built-in task named `wrapper`. Running `./gradlew wrapper --gradle-version 9.0` regenerates the wrapper files: it updates the `distributionUrl` in `gradle-wrapper.properties` to the requested version, and can refresh the `gradlew`/`gradlew.bat` scripts and `gradle-wrapper.jar`. Crucially you run it **with the current wrapper**, then commit the changed files so every developer and CI agent transparently downloads and uses the new version on their next invocation — no manual install needed. You can pass `--gradle-version latest` to track the newest release, or pin an exact version like `9.0`. It's good practice to run it twice (or use `--gradle-version`) so the wrapper itself is regenerated by the target version, ensuring the scripts/jar match.
code
bash · 7 lines# Upgrade the wrapper to Gradle 9.0 and fully regenerate its files
./gradlew wrapper --gradle-version 9.0
./gradlew wrapper --gradle-version 9.0 # run again so scripts/jar are produced by 9.0
# Verify, then commit everything the task touched
grep distributionUrl gradle/wrapper/gradle-wrapper.properties
git add gradlew gradlew.bat gradle/wrapper/ && git commit -m "Upgrade Gradle wrapper to 9.0"go deeper
Know the command ./gradlew wrapper --gradle-version X and that you commit the result.
Explain that it rewrites distributionUrl, why you might run it twice, and the difference between an exact pin and latest.
Discuss propagation to CI/teammates, committing all touched files atomically, and reproducibility implications of pinning vs latest.
Frame wrapper version governance as a fleet-wide reproducibility/supply-chain concern; standardize pinned versions and an upgrade cadence across repos.
## What the `wrapper` task is Every Gradle project gets a built-in task called `wrapper` (type `org.gradle.api.tasks.wrapper.Wrapper`). Its job is to *generate or regenerate* the four wrapper artifacts that let anyone build the project with zero pre-installed Gradle: - `gradle/wrapper/gradle-wrapper.properties` — the config, notably `distributionUrl` - `gradle/wrapper/gradle-wrapper.jar` — the tiny bootstrap that downloads/launches the distribution - `gradlew` / `gradlew.bat` — the launcher scripts ## Upgrading the version The canonical way to change the Gradle version is **not** to hand-edit `distributionUrl`. Instead you run the `wrapper` task with the `--gradle-version` flag: ```bash ./gradlew wrapper --gradle-version 9.0 ``` This updates `distributionUrl` to point at `gradle-9.0-bin.zip` (or `-all.zip`, see distribution type). On the **next** Gradle invocation, the bootstrap jar sees the new URL, downloads that distribution into `~/.gradle/wrapper/dists/`, and runs it. Because you commit the updated files, the upgrade propagates to every teammate and CI runner automatically. ## Why run it (and why twice) You run `wrapper` using the *currently installed* wrapper. That older wrapper writes the new `distributionUrl`, but the regenerated `gradlew` scripts and `gradle-wrapper.jar` are still produced by the *old* version's task. To make the wrapper files themselves match the target version, run the task again after the first upgrade (now executing under the new version): ```bash ./gradlew wrapper --gradle-version 9.0 # first: updates distributionUrl ./gradlew wrapper --gradle-version 9.0 # second: regenerates scripts/jar with 9.0 ``` ## Version selectors - `--gradle-version 9.0` — pin an exact version (recommended for reproducibility) - `--gradle-version latest` — resolve to the newest stable release at run time - `--gradle-version 9.0-rc-1` — release candidates and milestones are also valid ## What gets committed After running the task, `git status` should show changes to `gradle-wrapper.properties` (always) and possibly `gradlew`, `gradlew.bat`, `gradle-wrapper.jar`. Commit all of them together — a partial commit can leave scripts and the configured version out of sync.
- Why is running the `wrapper` task preferred over editing `distributionUrl` by hand?The task also regenerates the scripts and jar consistently, validates the version, and (when run twice) ensures the wrapper files are produced by the target version. Hand-editing only changes the URL and can leave scripts/jar mismatched.
- What does `--gradle-version latest` resolve to?It contacts the Gradle services and resolves to the newest stable release at the time you run the task, baking that concrete version into `distributionUrl`. It does not keep auto-updating later.
Like a self-updating installer: you run today's copy once to point it at the new download URL, then run the freshly downloaded copy so the installer itself is the new version.
- Claiming you must install Gradle locally to upgrade — the wrapper avoids that.
- Saying the upgrade happens immediately for everyone without committing the changed files.
- Thinking `--gradle-version latest` makes builds float forever (it resolves to a fixed version at run time).