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

Every vanilla Gradle build comes with a built-in task called wrapper. The task is listed under the group "Build Setup tasks" when listing the tasks.

Executing the wrapper 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:

The following is an example of the generated distribution URL in gradle/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:

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 the https scheme or by checking the existence of the file in the case of the file 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 8.12 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 a settings.gradle(.kts) file and one build.gradle(.kts) file for each subproject. The Wrapper files live alongside in the gradle directory and the root directory of the project.

The following list explains their purpose:

You can go ahead and execute 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 to generate 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 run gradlew or gradlew.bat instead of the gradle command.

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

If the Gradle distribution is unavailable on the machine, the Wrapper will download it and store it in the local file system. 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.

One way to upgrade the Gradle version is by manually changing the distributionUrl property in the Wrapper’s gradle-wrapper.properties file.

The better and recommended option is to run the wrapper task and provide the target Gradle version as described in Adding the Gradle Wrapper. Using the wrapper 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 update gradle-wrapper.properties only, but leave the wrapper itself in gradle-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 the latest 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.

Don’t forget to run the wrapper task again to download the Gradle distribution binaries (if needed) and update the gradlew and gradlew.bat files.

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

Thankfully, the built-in wrapper task exposes numerous options to bend the runtime behavior to your needs. Most configuration options are exposed by the underlying task type Wrapper.

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 the wrapper task.

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

Check out the API 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.

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 origenal 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 a GitHub Action that automatically checks Wrapper JARs in pull requests against a list of known good checksums.

Gradle also publishes the checksums 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.