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 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 init or creating the wrapper with gradle 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.

Download this Free Quick-Start Guide to building simple Java projects with Gradle.

  • Learn to create and build Java projects in Gradle.
  • Understand the Gradle fundamentals.