gradle wrapper --gradle-version: upgrade the Gradle wrapper

./gradlew wrapper --gradle-version 8.14.3 upgrades the project's Gradle wrapper: it writes the new version into gradle/wrapper/gradle-wrapper.properties. Run ./gradlew wrapper (or any task) a second time so the new Gradle version also regenerates gradlew, gradlew.bat and gradle-wrapper.jar with its own scripts, then commit all four files. Everybody who runs ./gradlew afterwards gets the new version.

Upgrade

./gradlew --version                                   # current wrapper version
./gradlew wrapper --gradle-version 8.14.3             # pin a version
./gradlew wrapper --gradle-version latest             # newest stable release
./gradlew wrapper                                     # second run: new scripts and JAR
./gradlew --version                                   # confirm
git add gradlew gradlew.bat gradle/wrapper/

Pass the exact version you want. Optional flags add a checksum and choose the distribution type:

./gradlew wrapper --gradle-version 8.14.3 --distribution-type all
./gradlew wrapper --gradle-version 8.14.3 --gradle-distribution-sha256-sum SHA256

The properties file

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip
distributionSha256Sum=SHA256

Editing distributionUrl by hand also changes the version, but running the wrapper task keeps the scripts and JAR in step and validates the arguments.

Options of the wrapper task

Pitfalls

• JDK compatibility. Every Gradle version supports a range of Java versions. Running a new JDK with an old Gradle fails with Unsupported class file major version; upgrading the wrapper is the usual fix. Check the compatibility matrix in the Gradle documentation before choosing a version.
• Deprecations become errors. Major upgrades remove APIs that the previous version only deprecated. Run ./gradlew build --warning-mode all on the old version first to see what will break.
• Plugins. Old versions of the Android Gradle Plugin, Kotlin or Spring Boot plugins may not support the new Gradle. Upgrade them in the same change.
• Missing JAR. If gradle-wrapper.jar is not committed (or is in .gitignore), CI fails with Could not find or load main class GradleWrapperMain.

How to confirm it worked

./gradlew --version prints the new Gradle version together with the JVM it runs on. git diff gradle/wrapper/gradle-wrapper.properties shows the new distributionUrl, and a clean ./gradlew build on CI confirms that the plugins work with it. See the Gradle wrapper for how the scripts find and download the distribution.

FAQ