Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Installing Gradle and the Gradle Wrapper

Install Gradle on Windows, macOS and Linux, check your JDK, and learn why every project should use the Gradle Wrapper (gradlew) instead of a global install.

To run Gradle you need two things: a Java Development Kit (JDK) and Gradle itself. The surprise for newcomers is that in a well-run project you rarely run a globally installed Gradle at all. Instead you run a small script that ships inside the repository, the Gradle Wrapper, which downloads the exact Gradle version the project wants. This lesson covers both: installing Gradle once, and using the wrapper every day.

The commands below are read-only because the site cannot install software. Where a runnable idea helps, a labelled stand-in follows.

Step 1: a JDK

Gradle itself is a Java program, so it needs a JDK or JRE to start. Check what you have:

Terminal
java -version
javac -version

Gradle 9 requires Java 17 or newer to run. Your project may compile with a different Java version (this is configured with toolchains, covered in the Gradle course later); the JDK that runs Gradle and the JDK that compiles your code are separate ideas.

Set JAVA_HOME to the JDK folder if java is not found on your PATH:

Terminal
# Linux or macOS
export JAVA_HOME=/usr/lib/jvm/temurin-21
# Windows (PowerShell)
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21"

Step 2: install Gradle

Pick the method that fits your system.

System Command
Any (with SDKMAN) sdk install gradle
macOS (Homebrew) brew install gradle
Windows (Scoop) scoop install gradle
Windows (Chocolatey) choco install gradle
Manual Download the binary zip from gradle.org, unpack it, and add its bin folder to PATH

Verify:

Terminal
gradle --version

The output shows the Gradle version, the Kotlin and Groovy versions it bundles, and the JVM and operating system it found. Always include this output when you ask for help.

Step 3: the Gradle Wrapper

A global install has a problem: every developer and every CI server might have a different version, and a build that works on Gradle 8.4 can fail on 9.0. The wrapper solves this by pinning the version in the project.

Generate it once, from a global Gradle, in your project folder:

Terminal
gradle wrapper --gradle-version 9.0.0

This creates five files that you commit to version control:

TEXT
my-project/
  gradlew                 # Unix shell script
  gradlew.bat             # Windows batch script
  gradle/wrapper/
    gradle-wrapper.jar    # tiny bootstrap program
    gradle-wrapper.properties

From now on, anyone (including your CI) runs ./gradlew build on Linux/macOS or gradlew.bat build on Windows. The first run downloads Gradle into ~/.gradle/wrapper/dists; later runs reuse it.

The important file is gradle-wrapper.properties:

PROPERTIES
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

To upgrade a project, run ./gradlew wrapper --gradle-version <new> and commit the changed files. Everyone on the team then upgrades automatically on their next build.

Use -bin distributions in the URL for CI and everyday work. The -all distribution also includes sources and documentation, which helps IDEs but is a bigger download.

What the wrapper does, step by step

flowchart TD
  A["./gradlew build"] --> B["Read gradle-wrapper.properties"]
  B --> C{"Version already in ~/.gradle/wrapper/dists?"}
  C -- "no" --> D["Download and unpack distributionUrl"]
  C -- "yes" --> E["Reuse it"]
  D --> E
  E --> F["Run that Gradle with your arguments"]

The wrapper downloads once, then behaves exactly like a normal gradle command.

A runnable stand-in: reading the wrapper properties

The stand-in below is not the wrapper. It reads a gradle-wrapper.properties-style text and extracts the Gradle version from the URL, which is the first thing the real wrapper does.

Java Stand-in: find the Gradle version in distributionUrl

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that Java's Properties class un-escapes \: for us. That is why the real file spells the URL https\://.

A runnable stand-in: a tiny gradlew in Bash

This is a toy launcher that mimics the "reuse or download" decision with plain files. Nothing is downloaded; it only prints what the real script would do.

Bash Stand-in: wrapper decision logic in Bash

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first call downloads, the second reuses. That is the whole trick behind reproducible builds.

Troubleshooting

  • gradlew: Permission denied: on Linux/macOS run chmod +x gradlew, and commit with git update-index --chmod=+x gradlew.
  • Unsupported class file major version: the JDK is newer or older than this Gradle version supports. Upgrade Gradle or choose another JDK.
  • Corporate proxy: set systemProp.https.proxyHost and systemProp.https.proxyPort in gradle.properties (see Properties).
  • Which Gradle is running? Run ./gradlew --version; if it prints a different version than you expect, you used the global gradle instead.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should a project commit the Gradle Wrapper files?

    The wrapper pins the Gradle version in gradle-wrapper.properties and downloads it on demand, so builds are reproducible.
  2. 2. Which command upgrades a project to a new Gradle version?

    Running the wrapper task rewrites gradle-wrapper.properties (and the jar/scripts); you then commit the result.
  3. 3. Where does the wrapper store the downloaded Gradle distribution?

    GRADLE_USER_HOME (by default ~/.gradle) holds wrapper/dists, so all projects share the cached distributions.
  4. 4. On Linux, ./gradlew says Permission denied. What is the fix?

    The script lost its executable bit (common on Windows checkouts). Make it executable and commit that mode.

Summary

  • Gradle needs a JDK to run; check java -version and JAVA_HOME.
  • Install a global Gradle once (SDKMAN, Homebrew, Scoop, or the zip), then use the wrapper per project.
  • gradle wrapper --gradle-version X creates gradlew, gradlew.bat and gradle/wrapper/*; commit them.
  • The wrapper reads gradle-wrapper.properties, downloads the distribution once, and runs it.
  • Upgrade by re-running the wrapper task, not by asking everyone to install a new version.

Next: Your First Gradle Build