Therecommended way to execute any Gradle build is with the help of the Gradle Wrapper (referred to as "Wrapper").

The Wrapper is a script (calledgradlew orgradlew.bat) that invokes a declared version of Gradle, downloading it beforehand if necessary.Instead of runninggradle build using the installed Gradle, you use the Gradle Wrapper by calling./gradlew build.

The Gradle Wrapper isn’t distributed as a standalone download—it’s created using thegradle wrapper task.

There are three ways to use the Wrapper:

1. Adding the Wrapper - You set up a new Gradle project andadd the Wrapper to it.

2. Using the Wrapper - Yourun a project with the Wrapper that already provides it.

3. Upgrading the Wrapper - Youupgrade the Wrapper to a new version of Gradle.

When using the Wrapper instead of the installed Gradle, you gain the following benefits:

• Standardizes a project on a given Gradle version for more reliable and robust builds.

• Provisioning the Gradle version for different users is done with a simple Wrapper definition change.

• Provisioning the Gradle version for different execution environments (e.g., IDEs or Continuous Integration servers) is done with a simple Wrapper definition change.

The following sections explain each of these use cases in more detail.

The Gradle Wrapper isnot something you download.

Generating the Wrapper files requires an installed version of the Gradle runtime on your machine as described inInstallation.Thankfully, generating the initial Wrapper files is a one-time process.

Every vanilla Gradle build comes with a built-in task calledwrapper.The task is listed under the group "Build Setup tasks" whenlisting the tasks.

Executing thewrapper task generates the necessary Wrapper files in the project directory:

The generated Wrapper properties file,gradle/wrapper/gradle-wrapper.properties, stores the information about the Gradle distribution:

• Theserver hosting the Gradle distribution.

• Thetype of Gradle distribution. By default, the-bin distribution contains only the runtime but no sample code and documentation.

• TheGradle version used for executing the build. By default, thewrapper task picks the same Gradle version used to generate the Wrapper files.

• Optionally, atimeout in ms used when downloading the Gradle distribution.

• Optionally, aboolean to set thevalidation of the distribution URL.

The following is an example of the generated distribution URL ingradle/wrapper/gradle-wrapper.properties:

All of those aspects are configurable at the time of generating the Wrapper files with the help of the following command line options:

--gradle-version

The Gradle version used for downloading and executing the Wrapper.The resulting distribution URL is validated before it is written to the properties file.

For Gradle versions starting with major version 9, the version can be specified using only the major or minor version number.In such cases, the latest normal release matching that major or minor version will be used.For example,9 resolves to the latest9.x.y release, and9.1 resolves to the latest9.1.x release.

The following labels are allowed:

• latest

• release-candidate

• release-milestone

• release-nightly

• nightly

--distribution-type

The Gradle distribution type used for the Wrapper.Available options arebin andall.The default value isbin.

--gradle-distribution-url

The full URL pointing to the Gradle distribution ZIP file.This option makes--gradle-version and--distribution-type obsolete, as the URL already contains this information.This option is valuable if you want to host the Gradle distribution inside your company’s network.The URL is validated before it is written to the properties file.

--gradle-distribution-sha256-sum

The SHA256 hash sum used forverifying the downloaded Gradle distribution.

--network-timeout

The network timeout to use when downloading the Gradle distribution, in ms. The default value is10000.

--no-validate-url

Disables the validation of the configured distribution URL.

--validate-url

Enables the validation of the configured distribution URL. Enabled by default.

If the distribution URL is configured with--gradle-version or--gradle-distribution-url, the URL is validated by sending a HEAD request in the case of thehttps scheme or by checking the existence of the file in the case of thefile scheme.

Let’s assume the following use-case to illustrate the use of the command line options.You would like to generate the Wrapper with version 9.2.1 and use the-all distribution to enable your IDE to enable code-completion and being able to navigate to the Gradle source code.

The following command-line execution captures those requirements:

As a result, you can find the desired information (the generated distribution URL) in the Wrapper properties file:

Let’s have a look at the following project layout to illustrate the expected Wrapper files:

A Gradle project typically provides asettings.gradle(.kts) file and onebuild.gradle(.kts) file for each subproject.The Wrapper files live alongside in thegradle directory and the root directory of the project.

The following list explains their purpose:

gradle-wrapper.jar

The Wrapper JAR file containing code for downloading the Gradle distribution.

gradle-wrapper.properties

A properties file responsible for configuring the Wrapper runtime behavior e.g. the Gradle version compatible with this version. Note that more generic settings, likeconfiguring the Wrapper to use a proxy, need to go into adifferent file.

gradlew,gradlew.bat

A shell script and a Windows batch script for executing the build with the Wrapper.

You can go ahead andexecute the build with the Wrapper without installing the Gradle runtime.If the project you are working on does not contain those Wrapper files, you will need togenerate them.

It is always recommended to execute a build with the Wrapper to ensure a reliable, controlled, and standardized execution of the build.Using the Wrapper looks like running the build with a Gradle installation.Depending on the operating system you either rungradlew orgradlew.bat instead of thegradle command.

The following console output demonstrates the use of the Wrapper on a Windows machine for a Java-based project:

If the Gradle distribution was not provisioned toGRADLE_USER_HOME before, the Wrapper will download it and store it inGRADLE_USER_HOME.Any subsequent build invocation will reuse the existing local distribution as long as the distribution URL in the Gradle properties doesn’t change.

Projects typically want to keep up with the times and upgrade their Gradle version to benefit from new features and improvements.

The recommended option is to run thewrapper task and provide the target Gradle version as described inAdding the Gradle Wrapper.Using thewrapper task ensures that any optimizations made to the Wrapper shell script or batch file with that specific Gradle version are applied to the project.

As usual, you should commit the changes to the Wrapper files to version control.

Note that running the wrapper task once will updategradle-wrapper.properties only, but leave the wrapper itself ingradle-wrapper.jar untouched.This is usually fine as new versions of Gradle can be run even with older wrapper files.

The following command upgrades the Wrapper to thelatest version:

The following command upgrades the Wrapper to a specific version:

Once you have upgraded the wrapper, you can check that it’s the version you expected by executing./gradlew --version.

Another way to upgrade the Gradle version is by manually changing thedistributionUrl property in the Wrapper’sgradle-wrapper.properties file.The tip above also applies in this case.

Most users of Gradle are happy with the default runtime behavior of the Wrapper.However, organizational policies, security constraints or personal preferences might require you to dive deeper into customizing the Wrapper.

Thankfully, the built-inwrapper task exposes numerous options to bend the runtime behavior to your needs.Most configuration options are exposed by the underlying task typeWrapper.

Let’s assume you grew tired of defining the-all distribution type on the command line every time you upgrade the Wrapper.You can save yourself some keyboard strokes by re-configuring thewrapper task.

With the configuration in place, running./gradlew wrapper --gradle-version 9.2.1 is enough to produce adistributionUrl value in the Wrapper properties file that will request the-all distribution:

Check out theAPI documentation for a more detailed description of the available configuration options. You can also find various samples for configuring the Wrapper in the Gradle distribution.

Authenticated Gradle distribution download

systemProp.gradle.wrapperUser=usernamesystemProp.gradle.wrapperPassword=password

distributionUrl=https://username:password@somehost/path/to/gradle-distribution.zip

Verification of downloaded Gradle distributions

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

The Wrapper JAR is a binary file that will be executed on the computers of developers and build servers.As with all such files, you should ensure it’s trustworthy before executing it.

Since the Wrapper JAR is usually checked into a project’s version control system, there is the potential for a malicious actor to replace the original JAR with a modified one by submitting a pull request that only upgrades the Gradle version.

To verify the integrity of the Wrapper JAR, Gradle has created aGitHub Action that automatically checks Wrapper JARs in pull requests against a list of known good checksums.

Gradle also publishes thechecksums of all releases (except for version 3.3 to 4.0.2, which did not generate reproducible JARs), so you can manually verify the integrity of the Wrapper JAR.

Automatically verifying the Gradle Wrapper JAR on GitHub

Manually verifying the Gradle Wrapper JAR

$ cd gradle/wrapper

$ curl --location --output gradle-wrapper.jar.sha256 \       https://services.gradle.org/distributions/gradle-9.2.1-wrapper.jar.sha256

$ echo " gradle-wrapper.jar" >> gradle-wrapper.jar.sha256

$ sha256sum --check gradle-wrapper.jar.sha256

gradle-wrapper.jar: OK

$ cd gradle/wrapper

$ curl --location --output gradle-wrapper.jar.sha256 \       https://services.gradle.org/distributions/gradle-9.2.1-wrapper.jar.sha256

$ echo " gradle-wrapper.jar" >> gradle-wrapper.jar.sha256

$ shasum --check gradle-wrapper.jar.sha256

gradle-wrapper.jar: OK

> $expected = Invoke-RestMethod -Uri https://services.gradle.org/distributions/gradle-9.2.1-wrapper.jar.sha256

> $actual = (Get-FileHash gradle\wrapper\gradle-wrapper.jar -Algorithm SHA256).Hash.ToLower()

> @{$true = 'OK: Checksum match'; $false = "ERROR: Checksum mismatch!`nExpected: $expected`nActual:   $actual"}[$actual -eq $expected]

OK: Checksum match

Troubleshooting a checksum mismatch

$ sha256sum gradle/wrapper/gradle-wrapper.jard81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95 gradle/wrapper/gradle-wrapper.jar

$ shasum --algorithm=256 gradle/wrapper/gradle-wrapper.jard81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95 gradle/wrapper/gradle-wrapper.jar

> (Get-FileHash gradle\wrapper\gradle-wrapper.jar -Algorithm SHA256).Hash.ToLower()d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95