Gradle Wrapper

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

The Wrapper is a script (called gradlew or gradlew.bat) that invokes a declared version of Gradle, downloading it beforehand if necessary. Instead of running gradle 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 the gradle :wrapper task.

There are three ways to use the Wrapper:

Adding the Wrapper - You set up a new Gradle project and add the Wrapper to it.
Using the Wrapper - You run a project with the Wrapper that already provides it.
Upgrading the Wrapper - You upgrade 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.

1. Adding the Gradle Wrapper

The Gradle Wrapper is not something you download.

Generating the Wrapper (and its files) requires an installed version of Gradle as described in Installation.

The Build Init Plugin (gradle init) automatically generates the Wrapper files when creating a new project.

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.

When invoking the wrapper task, use gradle :wrapper. The : prefix explicitly targets the root project, which is the only project where the wrapper task is relevant. This matters for Configure on Demand and Isolated Projects, where addressing the root project directly avoids unnecessary project configuration.

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

$ gradle :wrapper

> Task :wrapper

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

To make the Wrapper files available to other developers and execution environments, you need to check them into version control.

Wrapper files, including the JAR file, are small. Adding the JAR file to version control is expected. Some organizations do not allow projects to submit binary files to version control, and there is no workaround available.

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

The server hosting the Gradle distribution.
The type of Gradle distribution. By default, the -bin distribution contains only the runtime but no sample code and documentation.
The Gradle version used for executing the build. By default, the wrapper task picks the same Gradle version used to generate the Wrapper files.
Optionally, a timeout in ms used when downloading the Gradle distribution.
Optionally, a boolean to set the validation of the distribution URL.

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

distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.1-bin.zip

Use the -bin distribution for most builds.

The -bin distribution contains only the runtime needed to build and run Gradle. It’s smaller to download and faster to cache on CI systems compared to the -all distribution, which also includes Gradle’s full source code and documentation.

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.