Understanding the Gradle Wrapper
The vast majority of developers using Gradle use the Gradle Wrapper. This is great because using the Gradle Wrapper means that developers working on the project don’t need to manage their own Gradle installations. Being that the wrapper is so ubiquitous it is important to understand exactly what it does and what it does not do.
If you aren’t using the wrapper
If you aren’t already using the wrapper, you really should. Using the wrapper guarantees that every developer on your team is using the same version of Gradle and that they can run Gradle builds (even if they haven’t installed Gradle on their machine).
Getting started is easy. First install Gradle on your machine, then open up your project directory via the command line. Run
gradle wrapper and you are done! You can add the
--gradle-version X.Yargument to specify which version of Gradle to use.
Now you can run any Gradle task in your project using the
gradlew shell script or bat file located in your project’s root directory.
What the Gradle Wrapper is
The Gradle Wrapper consists of a few files in your project directory:
gradlew: The shell script Unix users can run to execute Gradle tasks
gradlew.batThe bat script Windows users can run to execute Gradle tasks
gradle/wrapper/gradle-wrapper.jarThe wrapper’s executable JAR; this is where the wrapper code resides
gradle/wrapper/gradle-wrapper.propertiesA properties file for configuring the wrapper
You should make sure all these are committed to version control. They are all small, system-independent, and critical to using the Gradle Wrapper.
What the Gradle Wrapper does
When you run the Gradle Wrapper it performs the following actions:
- Parse the arguments passed to
- Install the correct Gradle version
- Invoke Gradle to run the specified tasks
Note that the wrapper only accepts two optional configuration arguments:
--quietto suppress output
--gradle-user-hometo specify an alternate home directory for Gradle.
The Gradle installation step is the only one that is particularly interesting. First it will check your
GRADLE_USER_HOME for the desired Gradle distribution. If it already exists, the wrapper goes on to invoking Gradle. If the distribution doesn’t exist yet, the wrapper will download the distribution.
It is also important to note that the wrapper completely ignores any Gradle distribution on your system. The wrapper downloads and unzips Gradle distributions in its own separate directory and will only use those distributions for builds. The wrapper will use any global Gradle configuration such as a
gradle.properties file defined in your Gradle home directory when running tasks.
What the Gradle Wrapper doesn’t do
The Gradle Wrapper itself does not execute your tasks. All it does is ensure you have the desired Gradle distribution and then invoke it. The wrapper is a very thin layer to eliminate the need for devlelopers to manage distributions themselves.
This means that the wrapper is effectively completely decoupled from Gradle itself. A wrapper from 2014 can build a project using Gradle 4.0, and a wrapper installed today can build a project using Gradle 2.0.
If you encounter an issue with your builds, it is extremely unlikely that the wrapper is at fault since it primarily just invokes Gradle proper.
I mentioned earlier that one of the files the wrapper puts in your project is a configuration file at
This file typically looks something like this:
distributionPathspecify the path at which the wrapper will store Gradle distributions. By default
~/.gradle, so the wrapper will store Gradle distributions at
zipStorePath are very similar. These specify where the wrapper will store the zipped distributions it downloads.
distributionUrl is the one you likely care most about. This is what specifies what version of Gradle you want to use for your builds and where to download it from.
Since the wrapper is independent of the actual Gradle distribution you use to build your project, what do you update and when?
The wrapper documentation says this:
If you want to switch to a new version of Gradle you don’t need to rerun the
wrappertask. It is good enough to change the respective entry in the
gradle-wrapper.propertiesfile, but if you want to take advantage of new functionality in the Gradle wrapper, then you would need to regenerate the wrapper files.
You should keep your Gradle distribution as up-to-date as possible. This is as easy as updating the
distributionUrl in your
You typically don’t need to update the Gradle Wrapper, but you can do so by re-running the
gradle wrapper task after updating Gradle. You can do this using the wrapper by running
gradlew wrapper which has the benefit of using the wrapper’s Gradle distribution. Updating it won’t hurt, but don’t expect any crazy new features in the wrapper. It hasn’t meaningfully changed since 2014 (unless you get excited about seeing fewer dots).
Android developers should note that the version of Gradle is (mostly) independent from the Android plugin version and from the version of Android Studio you use. New versions of either the plugin or Studio may require an updated Gradle version, but you should be able to use newer Gradle versions with older plugins and Studio without any issues.