Upgrade with the wrapper task and the target version, run it a second time so every wrapper file updates, and commit the result. Then add distributionSha256Sum to gradle-wrapper.properties so a tampered or corrupted download fails the build. That keeps the whole team on one known Gradle version.
What the wrapper does
The Gradle documentation says the wrapper invokes a declared version of Gradle, downloading it first if necessary. The version lives in gradle/wrapper/gradle-wrapper.properties as the distributionUrl. Since Gradle 9.0.0 that version always uses the X.Y.Z format, so partial versions are not allowed there.
Gradle recommends committing the wrapper files to version control so other developers and environments use the same version. The jar is small and expected in the repository.
Upgrade steps
- Pick the target version.
- Run the wrapper task with that version.
- Run it again.
- Run your build and tests.
- Commit the changed files together.
./gradlew wrapper --gradle-version 9.8.1
./gradlew wrapper --gradle-version 9.8.1
The documentation explains why twice: the first run updates gradle-wrapper.properties only, and the second brings all wrapper files, including gradle-wrapper.jar, up to date. You can edit distributionUrl by hand, but the task is preferred because it also applies optimizations to the gradlew scripts.
Add checksum verification
You can add the SHA-256 hash of the distribution using the distributionSha256Sum property in gradle-wrapper.properties. Gradle reports a build failure if the configured checksum does not match the server's checksum.
One caveat in the docs: verification is only performed if the configured wrapper distribution has not been downloaded yet. A machine that already holds the distribution in its cache will not recheck it. A clean CI agent will. Also, the wrapper task fails if the property is present but no checksum is defined in the task configuration, so set it in both places.
Why bother
A build tool is code that runs with your credentials and touches every artifact. Pinning it with a version and a hash means two things: your builds are reproducible, and a swapped download is caught on a fresh machine.
When to bump
Treat the wrapper like any other dependency. Update it when:
- A release fixes a problem you hit
- Your JDK moves to a version the old Gradle does not support
- A scheduled monthly or quarterly review comes round
Do not leave it for years. The longer the gap, the bigger the migration.
Safeguard's dependency scanning reads Gradle projects and can show the library versions your build resolves, alongside the SBOM. A free scan is at gold.safeguard.sh/scan.
Common mistakes
The first mistake is running the wrapper task only once and wondering why the jar is old. The second is committing the properties file but not the scripts and jar, which leaves some developers on a mixed state. The third is adding a checksum copied from a place you did not verify. Take the hash from the official release page for the exact version, and compare it in a second window before you commit.
Also remember that a build tool upgrade can change plugin compatibility. Run the full test suite, not just a compile, and read the release notes for removed features before you merge.
Quick check
Why run the wrapper task twice?
The first run updates only gradle-wrapper.properties. The second updates all wrapper files, including the jar, per the Gradle documentation.
Does the checksum protect a developer who already has Gradle cached?
Not necessarily. Gradle only verifies it when the configured distribution has not been downloaded yet.
Sources
Last reviewed: 19 October 2026.
