skip to content

wrapper Task & --gradle-version

4 roadmaps5 questions

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.

on this pageshow

explore

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.

saying these in an interview costs you the question

  • 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

resolving links…

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