Chapter 64. The Gradle Wrapper

The Gradle Wrapper (henceforth referred to as the “wrapper”) is the preferred way of starting a Gradle build. The wrapper is a batch script on Windows, and a shell script for other operating systems. When you start a Gradle build via the wrapper, Gradle will be automatically downloaded and used to run the build.

The wrapper is something you should check into version control. By distributing the wrapper with your project, anyone can work with it without needing to install Gradle beforehand. Even better, users of the build are guaranteed to use the version of Gradle that the build was designed to work with. Of course, this is also great for continuous integration servers (i.e. servers that regularly build your project) as it requires no configuration on the server.

You install the wrapper into your project by running the wrapper task. (This task is always available, even if you don't add it to your build). To specify a Gradle version use --gradle-version on the command-line. You can also set the URL to download Gradle from directly via --gradle-distribution-url. If no version or distribution URL is specified, the wrapper will be configured to use the gradle version the wrapper task is executed with. So if you run the wrapper task with Gradle 2.4 and the wrapper configuration will default to Gradle 2.4.

Example 64.1. Running the wrapper task

Output of gradle wrapper --gradle-version 2.0

> gradle wrapper --gradle-version 2.0


Total time: 1 secs

The wrapper can be further customized by adding and configuring a Wrapper task in your build script, and then executing it.

Example 64.2. Wrapper task


task wrapper(type: Wrapper) {
    gradleVersion = '2.0'

After such an execution you find the following new or updated files in your project directory (in case the default configuration of the wrapper task is used).

Example 64.3. Wrapper generated files

Build layout


All of these files should be submitted to your version control system. This only needs to be done once. After these files have been added to the project, the project should then be built with the added gradlew command. The gradlew command can be used exactly the same way as the gradle command.

If you want to switch to a new version of Gradle you don't need to rerun the wrapper task. It is good enough to change the respective entry in the file, but if you want to take advantage of new functionality in the Gradle wrapper, then you would need to regenerate the wrapper files.

64.1. Configuration

If you run Gradle with gradlew, the wrapper checks if a Gradle distribution for the wrapper is available. If so, it delegates to the gradle command of this distribution with all the arguments passed originally to the gradlew command. If it didn't find a Gradle distribution, it will download it first.

When you configure the Wrapper task, you can specify the Gradle version you wish to use. The gradlew command will download the appropriate distribution from the Gradle repository. Alternatively, you can specify the download URL of the Gradle distribution. The gradlew command will use this URL to download the distribution. If you specified neither a Gradle version nor download URL, the gradlew command will download whichever version of Gradle was used to generate the wrapper files.

For the details on how to configure the wrapper, see the Wrapper class in the API documentation.

If you don't want any download to happen when your project is built via gradlew, simply add the Gradle distribution zip to your version control at the location specified by your wrapper configuration. A relative URL is supported - you can specify a distribution file relative to the location of file.

If you build via the wrapper, any existing Gradle distribution installed on the machine is ignored.

64.2. Verification of downloaded Gradle distributions

The Gradle Wrapper allows for verification of the downloaded Gradle distribution via SHA-256 hash sum comparison. This increases security against targeted attacks by preventing a man-in-the-middle attacker from tampering with the downloaded Gradle distribution.

To enable this feature you'll want to first calculate the SHA-256 hash of a known Gradle distribution. You can generate a SHA-256 hash from Linux and OSX or Windows (via Cygwin) with the shasum command.

Example 64.4. Generating a SHA-256 hash

> shasum -a 256

Add the returned hash sum to the using the distributionSha256Sum property.

Example 64.5. Configuring SHA-256 checksum verification


64.3. Unix file permissions

The Wrapper task adds appropriate file permissions to allow the execution of the gradlew *NIX command. Subversion preserves this file permission. We are not sure how other version control systems deal with this. What should always work is to execute “sh gradlew”.