One of the most common questions for anyone using Gradle is what’s the difference between gradle vs. gradlew. Each is a Gradle command with a particular use case in mind. Here you’ll learn what each command does, and when to use one over the other.
Quick summary If you’re working in a project that has a gradlew script, always use it. If it doesn’t, use the gradle command to generate it. To learn why, read on.
gradle command
If you go ahead and install Gradle from https://gradle.org/releases you’ll have available the gradle command, which lives in the installation’s bin directory. Remember to add the bin directory to your PATH environment variable
If you run gradle on the command line, you’ll see output like this:
Notice in the output it prints the version of Gradle. This is the version of the Gradle installation on the machine where the gradle command is run. This may sound obvious, but it’s an important distinction to make when we come to talk about gradlew shortly.
With a local installation of Gradle, you can do all sorts of things with the gradle command, including:
- creating a new Gradle project with
gradle initor creating the wrapper withgradle wrapper - from within a Gradle project, running a Gradle build with
gradle build - seeing what tasks are available in a Gradle project using
gradle tasks
All this uses your local Gradle installation with whatever version you have installed.
gradlew command
The gradlew command, also known as the Gradle wrapper, is a slightly different beast. It’s a script that comes packaged up within a project. Yes, it gets committed into version control so when you clone the project you get the gradlew script automatically.
So what? Well if you think about it, this has some significant advantages.
1. No need to install gradle locally
The gradlew script doesn’t rely on a local Gradle installation. It goes and fetches a Gradle installation from the internet the first time it runs on your local machine, and caches it. This makes it super-easy for anybody anywhere to clone a project and build it.
2. Fixed version
The gradlew script is tied to a specific Gradle version. That’s very useful, because it means whoever manages the project can enforce what version of Gradle should be used to build it. Gradle features are not always compatible between versions, so using the Gradle wrapper means the project will get built consistently every time. Of course, this relies on the person building the project ways using the gradlew command.
Here’s an example of running ./gradlew from within a project (this project in fact).
The output here is similar to what we had when we ran gradle. You can see that the version is different though, 6.6.1 vs. 6.8.2. That may or may not be important, but using gradlew avoids us having to think about any inconsistencies and we can be sure that all team members or CI servers are using the same Gradle version to build the project.
Everything you can do with the gradle command, you can also do with gradlew. To build a project would be ./gradlew build. Clone the project and try it out, if you want!
gradle and gradlew comparison
Hopefully you can see now that within a project using gradlew is always best option. Make sure that the gradlew script is checked into version control, so you and other developers get the benefits listed above.
That said, is there ever any reason to use the gradle command? Yes, if you’re setting up a new Gradle project in an empty directory you can use gradle init to do that. This command also generates the gradlew script for you too. It really is best practice to use gradlew!
| What do you want to do? | gradle or gradlew? |
|---|---|
| Build a project | gradlew |
| Test a project | gradlew |
| Run any other Gradle task in a project | gradlew |
| Initialise a project as a Gradle project or generate the Gradle wrapper | gradle |
To learn about initialising the Gradle wrapper, how to update it, and more check out the article What is the Gradle wrapper and why should you use it?
Stop reading Gradle articles like these
This article helps you fix a specific problem, but it doesn't teach you the Gradle fundamentals you need to really help your team succeed.
Instead, follow a step-by-step process that makes getting started with Gradle easy.
