| name | gradle-wrapper-update |
| description | Updates the Gradle wrapper by running the wrapper task twice, keeping the wrapper scripts, properties file, and jar consistent. Supports updating to the latest version or a specific version. Use whenever a Gradle project needs its wrapper upgraded or downgraded.
|
| license | Apache-2.0 |
| metadata | {"author":"huanshankeji","version":"1.0.0"} |
Updating the Gradle Wrapper
Background
The Gradle wrapper consists of four files that must all stay consistent:
gradle/wrapper/gradle-wrapper.properties — declares the Gradle
distribution URL and version.gradle/wrapper/gradle-wrapper.jar — the bootstrap jar that downloads the
declared distribution.gradlew — the POSIX shell script that invokes the bootstrap jar.gradlew.bat — the Windows batch script that invokes the bootstrap jar.
Both gradlew and gradlew.bat must exist so the project works on all
platforms. Do not manually edit any of these files. Always use the
wrapper task to perform a full, consistent update.
When to use
Apply this skill whenever you need to:
- Upgrade the Gradle wrapper to a newer Gradle version.
- Downgrade the Gradle wrapper to an older Gradle version.
Update procedure
Step 1: Run the wrapper task twice
Running the wrapper task once updates gradle-wrapper.properties and
regenerates the gradlew and gradlew.bat scripts. Running it a second
time lets the newly declared version of Gradle download itself and
regenerate the gradle-wrapper.jar with the correct version, ensuring all
four wrapper components are consistent.
Option A — update to the latest Gradle version (recommended starting point):
./gradlew wrapper --gradle-version=latest && ./gradlew wrapper
Try this first. If you need a specific version instead, use Option B.
Option B — update to a specific Gradle version:
./gradlew wrapper --gradle-version=<TARGET_VERSION> && ./gradlew wrapper
Replace <TARGET_VERSION> with the desired Gradle version, for example:
./gradlew wrapper --gradle-version=9.4.1 && ./gradlew wrapper
To find the version string for a specific release, consult its release notes
page. The latest release notes are always at
https://docs.gradle.org/current/release-notes.html, and a specific release
such as 9.4.1 is at https://docs.gradle.org/9.4.1/release-notes.html.
Step 2: Verify the update
Run ./gradlew -v to confirm the wrapper script works and to see the active
Gradle version:
./gradlew -v
Then check that gradle/wrapper/gradle-wrapper.properties references the
expected distribution URL:
cat gradle/wrapper/gradle-wrapper.properties
The distributionUrl line should contain the target version, for example:
distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.1-bin.zip
Step 3: Commit the changed files
Commit all four modified files together so the repository always contains a
consistent wrapper:
gradle/wrapper/gradle-wrapper.jar
gradle/wrapper/gradle-wrapper.properties
gradlew
gradlew.bat
Guardrails
-
Never manually edit gradle-wrapper.properties or any other wrapper
file. Always run ./gradlew wrapper so all four files are updated together.
-
Run the wrapper task twice as shown above. The first run updates the
properties and scripts; the second run lets the new Gradle version update the
jar.
-
After updating, run ./gradlew -v to verify the wrapper works, then run the
project's build or test task (e.g., ./gradlew build) to confirm the project
works correctly with the new Gradle version.
-
If the project uses a non-default distribution type (-all instead of
-bin), preserve that by passing --distribution-type=all:
./gradlew wrapper --gradle-version=latest --distribution-type=all && ./gradlew wrapper
References
