gradle-wrapper-update

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

• Gradle documentation: Upgrading the Gradle Wrapper
• Gradle release notes index