Gradle Wrapper

Introduction

The Gradle Wrapper is a small script (gradlew / gradlew.bat) plus metadata that downloads and runs a fixed Gradle version for the project. Teams commit Wrapper files so laptops and CI use the same Gradle without asking everyone to install globally. This chapter explains how it works and how to create or upgrade it.

Prerequisites

Wrapper Files

text
gradlew                 # Unix/macOS shell script
gradlew.bat             # Windows batch script
gradle/wrapper/
  gradle-wrapper.jar    # bootstrap downloader
  gradle-wrapper.properties

gradle-wrapper.properties

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

distributionUrl pins the Gradle version. Change it when upgrading (or use the command below).

Why Teams Commit the Wrapper

Without WrapperWith Wrapper
“Install Gradle 8.12” in READMEClone repo, run ./gradlew
CI image must preinstall GradleCI only needs JDK
Version drift between developersSame version everywhere

Tip

Best Practice

Treat gradlew, gradlew.bat, and gradle/wrapper/* as source code. Never add them to .gitignore.

Create Wrapper in a New Project

If you built a project manually without Wrapper:

bash
# From project root; requires global gradle once
gradle wrapper --gradle-version 8.12.1

Verify:

bash
./gradlew -version

Upgrade Wrapper Version

bash
./gradlew wrapper --gradle-version 8.12.1

Commit updated gradle-wrapper.properties (and jar if it changed). Teammates get the new version on next pull.

Run Builds Through Wrapper

bash
./gradlew build
./gradlew test
./gradlew clean build

Windows:

bat
gradlew.bat build

First run downloads Gradle into:

text
~/.gradle/wrapper/dists/

Later runs reuse the cache.

CI and Servers

Pipeline step (Linux):

yaml
- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
- run: chmod +x gradlew
- run: ./gradlew build

No apt install gradle required.

GRADLE_USER_HOME

Override cache location:

bash
export GRADLE_USER_HOME=/data/gradle-cache
./gradlew build

Useful in CI with persisted volumes.

Offline and Air-Gapped (Brief)

  1. Build once online to populate ~/.gradle/wrapper/dists and dependency cache
  2. Copy caches or use an internal mirror URL in distributionUrl and repository settings

Details vary by company infrastructure.

Wrapper vs Global gradle

CommandUses
gradle buildWhatever gradle is on PATH
./gradlew buildVersion from gradle-wrapper.properties

IDEA should use Wrapper for team projects (IntelliJ chapter).

Mini Example: Verify Team Alignment

bash
./gradlew -version

Everyone should report the same Gradle line before opening a PR.

FAQ

Is gradle-wrapper.jar safe to commit?

Yes—it is the official bootstrap from Gradle releases.

Can I delete gradlew and use global Gradle only?

Possible but discouraged—CI and onboarding suffer.

Wrapper download slow or blocked?

Check proxy; set systemProp in gradle.properties or use internal mirror.

What comes next?

Build script basics.