skip to content

wrapper Task & --gradle-version

Regenerating the wrapper with ./gradlew wrapper --gradle-version, and configuring the Wrapper task type. Asked because upgrading by hand-editing the properties file leaves the scripts and jar stale.

part ofGradleread it →
on this pageshow

questions

5

How do you upgrade the Gradle version used by a project's wrapper, and what command actually regenerates the wrapper files?

level: juniorimportance: must knowfreq 70%

answer

  1. ./gradlew wrapper --gradle-version
  2. rewrites distributionUrl
  3. run with current wrapper, then commit
  4. run twice to regenerate scripts/jar
  5. latest vs exact pin

basics

~10 s

Run ./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 s

Gradle 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
bash
# 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

for a junior

Know the command ./gradlew wrapper --gradle-version X and that you commit the result.

for a middle

Explain that it rewrites distributionUrl, why you might run it twice, and the difference between an exact pin and latest.

for a senior

Discuss propagation to CI/teammates, committing all touched files atomically, and reproducibility implications of pinning vs latest.

for a principal

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).

context

open as a page

How do you configure the `Wrapper` task type declaratively in build.gradle.kts instead of passing CLI flags each time?

level: middleimportance: should knowfreq 35%

basics

~10 s

Configure the built-in wrapper task in your build script: set gradleVersion, distributionType, and optionally distributionUrl/networkTimeout. Then ./gradlew wrapper regenerates files using those values without repeating CLI flags.

open as a page

What does the `--distribution-type` option (bin vs all) control when regenerating the wrapper, and when would you choose `all`?

level: middleimportance: should knowfreq 45%

basics

~10 s

--distribution-type picks which Gradle download the wrapper uses: bin (runtime only, smaller) or all (runtime plus sources and Javadoc). Choose all so IDEs can offer Gradle API source navigation and autocomplete.

open as a page

Your organization is air-gapped and cannot reach services.gradle.org. How do you regenerate the wrapper so builds fetch Gradle from an internal mirror?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Configure the wrapper to use an internal URL: set distributionUrl (in the wrapper task or properties) to your mirror's gradle-9.0-bin.zip. Regenerate with the wrapper task and commit, so every build pulls from the mirror.

open as a page

After running `./gradlew wrapper --gradle-version 9.0`, a colleague notices `gradlew` and `gradle-wrapper.jar` are unchanged in git, only the properties file changed. Is that a problem, and how do you ensure the jar/scripts are updated?

level: seniorimportance: nice to knowfreq 20%

basics

~20 s

Not necessarily a problem — the first run only rewrites distributionUrl; it doesn't always regenerate the scripts/jar. Run the wrapper task a second time (now under the new version) so gradlew, gradlew.bat, and gradle-wrapper.jar are regenerated.

open as a page