What is the Gradle wrapper and why should you use it?

What is the Gradle wrapper

Last Updated on March 17, 2021

The Gradle wrapper is a script that can be added to your Gradle project and used to execute your build. The advantage of this is that:

  • you don’t need to have Gradle installed on your machine to build the project
  • the wrapper guarantees you’ll be using the version of Gradle required by the project
  • you can easily update the project to a newer version of Gradle, and push those changes to version control to ensure other team members will use the newer version

Now you’ve got a flavour of what the Gradle wrapper is all about, let’s run through some common use cases.

How do I setup a new project with the Gradle wrapper?

To initially setup the wrapper, you will need to have Gradle installed on your machine first. Download it from the Gradle website, not forgetting to add the bin directory to your PATH environment variable.

Now in an empty directory you can run:

gradle wrapper

This has created some new files for us, which we can see if we inspect the directory:

We have 4 new files:

  • gradle-wrapper.jar code required for downloading the correct Gradle version when you run the build
  • gradle-wrapper.properties file to configure the wrapper’s properties such as the Gradle version
  • gradlew a shell script for executing the build on Linux
  • gradlew.bat a script for executing the build on Windows

These files should all be added into version control. This way, anyone checking out your project can immediately run a build.

Info: by default the Gradle wrapper created by running gradle wrapper will use the version of Gradle installed on your machine. Later on we discuss how to update this version.

How do I execute a Gradle build using the wrapper?

That’s precisely what gradlew and gradlew.bat are for. When you run these scripts a Gradle build will start using the configured version of Gradle.

On Linux based operating systems run:


And on Windows run:


We’ll be using the Linux version of the wrapper for the examples in the rest of the article, but you can use either depending on your setup.

Of course to do anything useful you’ll need to pass a task name to the Gradle wrapper script, using the format ./gradlew <task-name>. Here are some examples:

Initialise a project

Our next step might be to initialise a Gradle project:

./gradlew init

This will go off and setup a default settings.gradle and build.gradle file for your project.

Running a build

Optionally, we might want to run the build itself in an existing project:

./gradlew build

How do I see what version of Gradle the wrapper is using in a project?

That’s easy, just run ./gradlew --version:

Or you can also inspect the contents of the gradle/wrapper/gradle-wrapper.properties file mentioned earlier:

Right now this project is on version 6.1.1. We can see from the Gradle releases page that at the time of writing the latest version is 6.2.2. We better sort that out as we always want to be on the latest tech, right? ✅

How do I update the version of Gradle using the wrapper?

Just run this command:

./gradlew wrapper --gradle-version <version-number>

So if we wanted to update to version 6.2.2, we’d run:

And just as described in the previous section, we can verify this using ./gradlew --version:

Awesome, we’re on the correct version! 🐘

If you’re observant you might notice that at the beginning of the above execution the Gradle wrapper is downloading the newer version of Gradle, which brings us to:

Where does the Gradle wrapper store Gradle?

As discussed, the wrapper ensures you’re executing tasks with the correct version of Gradle, without having to have Gradle installed on your machine.

If the wrapper were to download Gradle every time you ran a Gradle task though, that would get very annoying very quickly. Consequently, the wrapper caches Gradle versions in the .gradle/wrapper/dists directory in your user home directory:

Here you’ll also find any other versions of Gradle you’ve used before.

Final info on the Gradle wrapper

One final tip: when you’re not sure about what tasks you can run in a given context execute the tasks task to find out:

./gradlew tasks

To learn more about configuring the Gradle wrapper, see these Gradle docs.

If you’re using IntelliJ IDEA as your IDE, check out this article which describes how to create a Gradle project (including wrapper) through the IDE.


If you prefer to learn in video format, check out this accompanying video to this post on the Tom Gregory Tech YouTube channel.

Gradle icon

Want to learn more about Gradle?
Check out the full selection of Gradle tutorials.

Get going with Gradle course
What is the Gradle wrapper and why should you use it?

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to top

Get the newsletter

Found this article helpful? Subscribe for monthly updates.

✅ All of my latest articles for the month
✅ Access to video tutorials
✅ Exclusive tips not found on my website