3 tips to configure the Gradle Wrapper & Distribution

Maxi Rosson
Apr 20 · 4 min read

These 3 ideas can help you to correctly configure the Gradle Wrapper and Distribution.

The recommended way to execute any Gradle build is with the help of the Gradle Wrapper (in short just “Wrapper”). The Wrapper is a script that invokes a declared version of Gradle, downloading it beforehand if necessary. As a result, developers can get up and running with a Gradle project quickly without having to follow manual installation processes saving your company time and money.

The Wrapper workflow

Here you can read more about the Gradle Wrapper.

1. How to correctly upgrade Gradle version

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

But, the better and recommended option is to run the following command:

./gradlew wrapper --gradle-version X.Y.Z

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.

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 ancient wrapper files. If you nevertheless want all the wrapper files to be completely up-to-date, you’ll need to run the wrapper task a second time.

The Gradle distribution zip file comes in two flavors:

  • Binary-only (-bin.zip)
  • Complete, with docs and sources (-all.zip)

In your development environment, is a good idea to download the complete distribution, so you can see the sources while developing and debugging your Gradle scripts.

So, your gradle/wrapper/gradle-wrapper.properties file should look like this:


You can also add this config to your root build.gradle file:

wrapper {
distributionType = Wrapper.DistributionType.ALL

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

You can read this article to see how you can automate Gradle (and also other dependencies) upgrades:

2. Switch to Gradle Binary Distribution on your CI environment

You don’t need the complete Gradle distribution on your CI environment. It takes more time to download the sources & docs, and also use more disk storage. So, you can execute the following simple script before running any Gradle task on your CI environment, to switch to Gradle Binary Distribution:

sed -i -e 's/-all.zip/-bin.zip/' gradle/wrapper/gradle-wrapper.properties

If you use Circle CI, you can define a custom_checkout command and use it instead of checkout, so you always switch to Gradle Binary Distribution immediately after a checkout:


- checkout
- run:
name: Switch to Gradle Binary Distribution
command: sed -i -e 's/-all.zip/-bin.zip/' gradle/wrapper/gradle-wrapper.properties

3. Verify the integrity of the Gradle Wrapper JAR

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 be sure that 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 seemingly only upgrades the Gradle version. Here you can find more official information about this topic.

The following script verifies the checksum of the Wrapper JAR to ensure that it has not been tampered.

You can add a verification step on your CI tool, and run that script on every push.

If you use Circle CI, then you can use this step to execute the verification:

- run:
name: Verify the integrity of the Gradle Wrapper JAR
command: |
cd gradle/wrapper
gradleVersion=$(grep "distributionUrl" gradle-wrapper.properties | grep -Po "(\d+\.)+\d+")
curl --location --output gradle-wrapper.jar.sha256 https://services.gradle.org/distributions/gradle-${gradleVersion}-wrapper.jar.sha256
echo " gradle-wrapper.jar" >> gradle-wrapper.jar.sha256
sha256sum --check gradle-wrapper.jar.sha256
Follow us for more productivity tools & ideas for Android, Kotlin & Gradle projects.


Boost your Productivity

Maxi Rosson

Written by

Developer Productivity Engineer | Android | Productivity tools & ideas for Android, Kotlin & Gradle developers on medium.dipien.com



Productivity tools & ideas for Android, Kotlin & Gradle developers.

Maxi Rosson

Written by

Developer Productivity Engineer | Android | Productivity tools & ideas for Android, Kotlin & Gradle developers on medium.dipien.com



Productivity tools & ideas for Android, Kotlin & Gradle developers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store