skip to content

Wrapper Scripts & Files

4 roadmaps5 questions

The four committed wrapper files and why they belong in version control. Asked because 'why is there a jar checked into this repository?' is a natural follow-up question.

on this pageshow

explore

questions

5

What are the files that make up the Gradle Wrapper, and what is each one responsible for?

level: juniorimportance: must knowfreq 70%

answer

  1. gradlew + gradlew.bat
  2. gradle-wrapper.jar = bootstrapper
  3. gradle-wrapper.properties = distributionUrl
  4. commit all four
  5. JDK-only, no Gradle install

basics

~10 s

Four committed files: gradlew (Unix script), gradlew.bat (Windows script), gradle/wrapper/gradle-wrapper.jar (the bootstrapping code), and gradle/wrapper/gradle-wrapper.properties (which Gradle version/distribution to use).

solid answer

~40 s

The Wrapper is a small committed bootstrapper that lets anyone build the project without pre-installing Gradle. It is four files: - `gradlew` — POSIX shell launcher run on Linux/macOS. - `gradlew.bat` — the Windows batch equivalent. - `gradle/wrapper/gradle-wrapper.jar` — the tiny Java program the scripts invoke; it reads the properties, downloads the declared Gradle distribution if absent, caches it under the Gradle user home, then hands off to the real Gradle. - `gradle/wrapper/gradle-wrapper.properties` — configuration naming the exact distribution (notably `distributionUrl`) so the build's Gradle version is pinned per project. You commit all four to version control and invoke `./gradlew <task>` instead of a system `gradle`. This guarantees every developer and CI machine runs the identical, reproducible Gradle version.

code

bash · 11 lines
bash
project/
  gradlew
  gradlew.bat
  gradle/
    wrapper/
      gradle-wrapper.jar
      gradle-wrapper.properties

# usage
./gradlew build      # Unix/macOS
gradlew.bat build    # Windows

go deeper

for a junior

Name the four files and state that you run ./gradlew instead of a system gradle.

for a middle

Explain each file's job and that the jar bootstraps/downloads the pinned distribution.

for a senior

Tie it to reproducibility: committed wrapper = identical Gradle for every dev and CI runner from a JDK-only clone.

for a principal

Frame it as a supply-chain/reproducibility contract enforced org-wide; touch on caching location and the bootstrap-vs-distribution separation.

## What the Wrapper is The **Gradle Wrapper** is a small bootstrapping layer committed *into* the project so that building requires only a JDK — not a pre-installed Gradle. You run `./gradlew build` instead of `gradle build`, and the wrapper makes sure the *correct* Gradle version is present before delegating to it. ## The four files 1. **`gradlew`** — a POSIX shell script at the project root. It locates a Java runtime, computes the classpath to the wrapper jar, and launches it. This is what you execute on Linux/macOS. 2. **`gradlew.bat`** — the Windows batch-file counterpart of `gradlew`, doing the same job for `cmd`/PowerShell users. 3. **`gradle/wrapper/gradle-wrapper.jar`** — a *very* small Java program (the wrapper bootstrap, class `org.gradle.wrapper.GradleWrapperMain`). The scripts run this jar. It reads the properties file, and if the named Gradle distribution is not already cached in the Gradle user home (default `~/.gradle/wrapper/dists`), it downloads and unpacks it, then invokes that real Gradle distribution with your arguments. 4. **`gradle/wrapper/gradle-wrapper.properties`** — a plain key/value file. The key field is `distributionUrl`, which names the exact Gradle distribution (e.g. `gradle-8.7-bin.zip`). Because this URL pins a specific version, the build's Gradle version is fixed *per project*. ## Why all four are committed All four are checked into version control. A fresh clone on any machine — a teammate's laptop, a CI runner, a reviewer's box — can run `./gradlew` and get the *identical* Gradle version with no manual install step. This is the foundation of reproducible builds in the Gradle ecosystem. ```bash # Fresh clone, nothing installed but a JDK: git clone https://example.com/app.git cd app ./gradlew build # downloads the pinned Gradle, then builds ``` ## Common misconception The wrapper jar does **not** contain Gradle itself — it is only the bootstrap that *fetches* Gradle. The actual multi-megabyte distribution is downloaded on first use and cached outside the repo.

  • Does gradle-wrapper.jar contain the full Gradle distribution?
    No. It is a tiny bootstrapper that reads the properties file and downloads/caches the real Gradle distribution on first run; the distribution lives outside the repo in the Gradle user home.
  • Which of the four files should be committed to version control?
    All four. Committing them is the entire point — a clone with only a JDK can build immediately and reproducibly.

Like a tiny vending-machine token committed in the repo: it doesn't hold the soda (Gradle), it knows exactly which can to fetch and dispenses the right one every time.

saying these in an interview costs you the question

  • Saying the wrapper jar bundles Gradle itself.
  • Suggesting you should gitignore gradlew/gradle-wrapper.jar.
  • Confusing the wrapper with a system-installed Gradle.

context

resolving links…

open as a page

Why does the Gradle Wrapper pin the build's Gradle version per project, and what problems does that solve?

level: middleimportance: must knowfreq 65%

basics

~10 s

The wrapper records a specific Gradle distribution in the project, so everyone runs the same version. This makes builds reproducible and prevents 'works on my machine' failures from version drift.

open as a page

What is the difference between invoking ./gradlew and a system-installed gradle, and which should a team prefer?

level: middleimportance: should knowfreq 55%

basics

~10 s

./gradlew runs the project's pinned Gradle via the committed wrapper; system gradle runs whatever version you installed globally. Teams should prefer ./gradlew for consistency and reproducibility.

open as a page

Which wrapper files belong in version control, and what practical pitfalls (line endings, executable bit, .gitignore) trip teams up?

level: seniorimportance: should knowfreq 45%

basics

~10 s

Commit all four wrapper files (gradlew, gradlew.bat, gradle-wrapper.jar, gradle-wrapper.properties). Pitfalls: accidentally gitignoring the jar, losing gradlew's executable bit, and CRLF line endings breaking the Unix script.

open as a page

Walk through what happens, step by step, when a developer runs ./gradlew build on a fresh clone.

level: seniorimportance: should knowfreq 40%

basics

~10 s

gradlew finds Java and runs gradle-wrapper.jar; the jar reads gradle-wrapper.properties, downloads the named Gradle distribution to the cache if absent, then delegates to that Gradle to execute the build task.

open as a page