Gradle Wrapper

The Gradle documentation recommends running every build through the wrapper. The wrapper is not a separate download: it is generated by the built-in wrapper task and consists of two scripts (gradlew for Unix shells, gradlew.bat for Windows), a small JAR with the download code and a properties file that names the Gradle distribution. A developer or a CI job runs ./gradlew build instead of gradle build; if the distribution named in the properties file is not in the Gradle User Home yet, the JAR downloads and unpacks it, and every later call reuses the unpacked copy. The benefits the manual lists are:

Two more consequences matter in practice. An old branch builds with the Gradle it was written for, even after the team moved on, which is how the removals of Gradle 9 (see Versions, Compatibility & Release History) stay a decision per branch instead of a surprise. And a new colleague needs a JDK and nothing else: there is no "install Gradle X and put it on the PATH" step in the README. The wrapper does not remove the need for a JDK, and it cannot be created without a Gradle: the first gradle wrapper needs an installed Gradle (or gradle init, which also generates the wrapper) once.

The same idea exists in Maven as the Maven Wrapper (mvnw, see Maven Wrapper); Ant has no wrapper, its installation is a directory you unpack (see Ant Installation). The comparison table at the end of this page lines up the three.

Source: Gradle User Manual: Gradle Wrapper

./gradlew is a shell script. It finds a Java (JAVA_HOME if set, otherwise java on the PATH), then starts it with the wrapper JAR. The JAR reads gradle/wrapper/gradle-wrapper.properties, looks for the distribution in the Gradle User Home, downloads and verifies it if absent, and finally starts the Gradle launcher of that distribution, which connects to a daemon or starts one (see Gradle Daemon).

The script itself is short (248 lines for Unix, 112 for Windows in 9.8.1). Its documented knobs are environment variables: JAVA_HOME selects the Java (a wrong value stops the script before anything else, see Error messages), and JAVA_OPTS and GRADLE_OPTS add JVM options, appended to the default -Xmx64m -Xms64m of the small wrapper JVM. The variables Gradle itself reads are on Build Environment & Properties. The JAR is 48,749 bytes in 9.8.1 and contains the classes of org.gradle.wrapper (GradleWrapperMain, Download, Install, WrapperExecutor and a few helpers). The wrapper clients still run on a very old JVM (JVM 8 for the wrapper, see the compatibility page), while Gradle 9 needs a JVM 17 or newer to run the build; with a JDK 17 in JAVA_HOME the same wrapper reported:

(The home directory is replaced by ... in the second line.) Which JVM runs the daemon, and how a project can declare it, is covered with the daemon and the toolchains.

Source: Gradle User Manual: Gradle Wrapper and Gradle User Manual: Compatibility Matrix

Every Gradle build has a built-in wrapper task in the "Build Setup" group. Run it on the root project (the colon prefix targets the root project, the only place where the task is relevant, and avoids configuring other projects with configure on demand or Isolated Projects). In an empty project, with the installed Gradle 9.8.1:

The task wrote four files; the listing also shows the settings.gradle.kts that already existed:

By default the task writes the version of the Gradle that runs it and the -bin distribution. gradle init generates the same files as part of a new project (the generated .gitattributes and .gitignore are described under Files to commit), and the Gradle properties file carries no distributionSha256Sum unless you ask for one (see Verifying the distribution and the wrapper JAR). In a multi-project build the wrapper files live next to the root settings.gradle(.kts), so that ../../gradlew tasks from a subproject directory finds the same scripts; the scripts find their own JAR, so they can be called from any directory.

Source: Gradle User Manual: Adding the Gradle Wrapper

The same layout applies to the Groovy DSL, with settings.gradle and build.gradle; gradlew.bat was not run here, because the runs were on macOS. All four wrapper files go into version control. The JAR is a binary and small (48 KB), and committing it is the expected practice: without it the first command of a fresh clone has nothing to run. The manual notes that some organisations do not allow binary files in version control and that there is no workaround then. A wrapper that is not committed is just a script nobody can use, so the alternative is to generate it in CI before the build, which loses the benefit of reviewing it.

Line endings matter for the two scripts: a gradlew saved with CRLF endings fails on Unix, and a gradlew.bat with LF endings is unreliable on Windows. gradle init therefore writes a .gitattributes (since Gradle 6.0, which added it to make sure the batch scripts keep their line endings). The file generated by 9.8.1 is:

The .gitignore that gradle init generates lists .gradle, build and .kotlin and does not ignore *.jar, so the wrapper JAR is not excluded by default. If your own .gitignore has a rule such as *.jar, add an exception for gradle/wrapper/gradle-wrapper.jar; the symptom of forgetting it is a clone whose ./gradlew stops at once with Java’s own message, which does not mention the wrapper:

(That was a copy of the skeleton without the JAR; the exit status was 1.)

Source: Gradle User Manual: Adding the Gradle Wrapper and Gradle 6.0 release notes: gradle init generates a .gitattributes file

Using the wrapper is running the build with ./gradlew on macOS and Linux, or gradlew.bat on Windows, instead of gradle; the arguments are the same. Call it from the root, or with the right relative path from a subproject (../gradlew tasks). Any installed Gradle is ignored. On the first call with an empty Gradle User Home, in a copy of the tidepool skeleton whose distributionUrl points at the local copy of the 9.8.1 zip:

With a real distribution URL the second line is Downloading https://services.gradle.org/distributions/gradle-9.8.1-bin.zip. The progress bar is a percentage since Gradle 6.0, and since the same release the wrapper reinstalls a distribution it finds invalid instead of failing and requiring manual intervention. The second call prints only the --version block, because the distribution is already unpacked. Both calls used a fresh Gradle User Home, whose wrapper directory afterwards looked like this:

The layout is wrapper/dists/<distribution name>/<hash derived from the distribution URL>/: the unpacked gradle-9.8.1 directory plus a lock file and a .ok marker that says the unpacking finished. A different URL for the same version (a company mirror, -all instead of -bin) has a different directory, so both can coexist. The download itself is removed after unpacking in these runs. The same Gradle User Home also holds the dependency cache and the daemon registry, which is why CI caches wrapper/dists along with it (see CI and IDE Integration). GRADLE_USER_HOME moves the whole directory; it is how the scratch runs of this page kept the real one untouched.

Source: Gradle User Manual: Using the Gradle Wrapper, Gradle 6.0 release notes: download progress and Gradle 6.0 release notes: recovering from an invalid installation

All keys, with the values 9.8.1 writes. distributionBase and zipStoreBase accept GRADLE_USER_HOME (the default) or PROJECT, the two values of the task’s PathBase.

The PROJECT value stores the distribution in the repository, which would make a download unnecessary (the DSL reference describes exactly this use, for custom snapshots). It works; with distributionBase=PROJECT, distributionPath=.gradle-dist and the two zip-store keys set the same way, a fresh Gradle User Home stayed empty (only native) and the project directory received:

That directory is about 150 MB; committing it is rarely a good idea, and the default is the right choice for almost every project. Properties that older Gradle versions wrote (urlRoot, distributionName, distributionVersion, distributionClassifier) were removed in Gradle 3.0.

Source: DSL reference: Wrapper and Gradle 3.0 release notes: removed wrapper properties

Upgrading Gradle is running the wrapper task again with the new version. The manual recommends the task over editing the file, because the task also refreshes the scripts, which sometimes change between Gradle versions. For 9.8.1 the release notes give the command as:

The first call runs the task with the old Gradle and rewrites the properties; the second call runs with the new Gradle (downloaded at that moment) and so also rewrites gradle-wrapper.jar and the scripts with the new Gradle’s versions. One run keeps the JAR untouched, which is usually fine because a new Gradle runs with older wrapper files, but the second run brings everything up to date. After upgrading, ./gradlew --version confirms the version; commit the four wrapper files together.

Only 9.8.1 could be used for the runs, so the upgrade was exercised as a switch to 9.7.1 (the mechanics are the same, only the direction differs, and nothing was downloaded; both URLs were validated with a HEAD request). The project had a distributionSha256Sum, the situation of every hardened project, and the first call stopped:

That is the task protecting you from a stale checksum: the old sum cannot be right for a new version, so the task refuses to write an unchecked URL beside it. The SHA-256 of 9.7.1 is published in a small .sha256 file next to the distribution (gradle-9.7.1-bin.zip.sha256), which was fetched for this run (about 64 bytes, not the distribution). With the sum:

The last two lines are the matching lines of the properties file afterwards. The JAR was byte-for-byte the 9.8.1 one (3b8a25775a69158b5ad2b1d17a80a88dc7b40a352a73eb27d06c612a7ce68e98) because it was written by the Gradle that ran the task, which is why a second call under the new Gradle is part of the official command. The second call, which would download 9.7.1, was not run here.

One more observation, easy to miss in review. When the version that is requested is the version of the Gradle that runs the task, an existing sum is carried over, which is the behaviour the manual describes for a version that does not change. With a properties file for 9.7.1 (URL and sum), running the installed 9.8.1 as gradle :wrapper --gradle-version 9.8.1 succeeded, and the only change in the file was the URL:

The 9.7.1 sum stayed next to the 9.8.1 URL, which fails at the first ./gradlew with the checksum error shown under Error messages. So always pass --gradle-distribution-sha256-sum when the version changes, and read the diff of gradle-wrapper.properties before committing.

Editing distributionUrl by hand also works, and so does editing it with a pull-request bot. The caveat of the manual applies: run the wrapper task afterwards to refresh the scripts and JAR.

Source: Gradle User Manual: Upgrading the Gradle Wrapper, Gradle 9.8.1 release notes and Gradle: release checksums

The options above are properties of the Wrapper task, so you can set them once in the build instead of retyping them. The manual’s example fixes the distribution type to all. Here is the same idea with the properties a hardened project cares about. The sum is that of gradle-9.8.1-all.zip, published by Gradle.

Both versions were run (in two copies of the skeleton, one with build.gradle.kts and one with build.gradle) with gradle :wrapper --configuration-cache; the output was identical in the two:

and they wrote the same properties file, with the all URL, the sum, and the three numbers:

A second call printed Reusing configuration cache., > Task :wrapper UP-TO-DATE and Configuration cache entry reused., so the configuration is configuration-cache compatible. With these properties in the build, ./gradlew :wrapper alone is the whole upgrade command: change gradleVersion and the sum in one commit, and run the task. The properties distributionSha256Sum, retries and retryBackOffMs worked in the build script of 9.8.1 as shown, although the DSL reference page does not list them among its properties on 2026-10-16; the command-line options always do.

Source: Gradle User Manual: Customizing the Gradle Wrapper and DSL reference: Wrapper

The default is services.gradle.org. Reasons to change it are a build network that blocks that host, a repository manager that mirrors it, or a build that must not depend on the public internet at all. In each case the change is the distributionUrl:

Unlike the Maven Wrapper, the Gradle documentation describes no MVNW_REPOURL-style variable that rewrites the host; the URL is the single source (see the comparison table). The company URL is still checked by distributionSha256Sum, and the sum is the one published by Gradle: it identifies the content, not where it came from.

Source: Gradle User Manual: Adding the Gradle Wrapper and Gradle User Manual: Accessing the web via a proxy

The wrapper can download from a server that wants HTTP Basic credentials or, since Gradle 9.4, a static Bearer token. Both are system properties, read from the Gradle User Home’s gradle.properties (or any other way of setting system properties); Basic credentials can also be embedded in the URL. The manual states the rules:

(The ${PLACEHOLDER_USER} values are not interpolated by Gradle; they stand for a value your secret store provides when the file is generated.) A real HTTPS server was not available, so the following was run against a server on localhost serving the same ZIP over plain http, with the host key localhost. The server, a few lines of Python 3, answers 401 unless the right header arrives, and logs the scheme of the Authorization header (never its value):

Each case below used an empty Gradle User Home, a copy of the skeleton with distributionUrl=http\://localhost\:18099/gradle-9.8.1-bin.zip, and ./gradlew --version. Without credentials (the server started with --basic ci-reader:demo-password):

(The frames after Download.download are left out.) With Basic credentials for the host in the Gradle User Home:

The client prints the warning every time it sends credentials over http. With the credentials in the URL (http\://ci-reader\:demo-password@localhost\:18099/gradle-9.8.1-bin.zip in the properties file) the server again saw Basic and the wrapper masked the user information in its own message as Downloading http://***@localhost:18099/gradle-9.8.1-bin.zip; the file, however, is committed to version control and holds the password in plain text, which the manual reserves for controlled environments. With the unprefixed properties systemProp.gradle.wrapperUser and systemProp.gradle.wrapperPassword the request also carried Basic and succeeded: the unprefixed form is sent to whatever host the URL names, which is the leak the host prefix prevents. With a Bearer token:

With the token and the user and password for the same host all set, the server again saw only Bearer, as documented. With a token configured for a different host (systemProp.gradle.other_example_com.wrapperToken), the request to localhost carried no Authorization header at all (Authorization=none -> 401), so the token was not leaked. And since these are ordinary system properties, the same token worked when supplied as GRADLE_OPTS="-Dgradle.localhost.wrapperToken=demo-token" in the environment instead of a file, which is the form a CI job uses with a secret variable. That is the safe place for the value: never in gradle-wrapper.properties, which is in the repository (see Build Environment & Properties for keeping secrets out of the project, and the Maven equivalent, MVNW_USERNAME and MVNW_PASSWORD, on Maven Wrapper).

Basic and Bearer authentication over HTTPS, and with a real repository manager, were not run here. Bearer authentication needs the wrapper of Gradle 9.4 or newer; on Gradle 8.14 only the Basic credentials exist (not run here, from the 9.4.0 release notes).

Source: Gradle User Manual: Authenticated Gradle Distribution Download and Gradle 9.4.0 release notes: Bearer token authentication for wrapper download

Since Gradle 9.5 the wrapper can retry the download. It is off by default, to preserve the behaviour of earlier versions. The two properties are in gradle-wrapper.properties:

retries is the maximum number of extra attempts, retryBackOffMs the initial delay, doubled after each failure. The manual’s snippet shows an explanation after a # on the same line, which does not work in a .properties file (see below); keep comments on their own lines. With the server answering 503 for the first two requests and a one-line change to retries=3 and retryBackOffMs=200 (200 ms to keep the demo short):

With the default retries=0 the first 503 ended the call (Attempt 1/1 failed), and with retries=1 the third request never came: both attempts failed with the same exception (Attempt 2/2 failed). Retries cover transient server and network problems; they are no remedy for a wrong URL or credentials, which fail the same way every time.

A classic bug follows from the properties format. Java properties files only know comments at the start of a line, so a trailing # comment becomes part of the value. With retries=3 # max attempts the wrapper did not even start:

The manual’s snippet puts such a comment after retryBackOffMs=1000 and the 9.5.0 release notes after both lines; copied literally they hit the same problem (only the retries case was run here). The retry feature does not exist in Gradle 8.14 (not run here); a wrapper JAR from 8.14 would not use the keys.

Source: Gradle User Manual: Configuring Wrapper Retries and Gradle 9.5.0 release notes: automatic retries for wrapper downloads

The wrapper downloads a program and the project then executes it, with a second binary (the JAR) committed to the repository. Gradle offers two independent checks.

Every message in the table was produced by a run on this page.

Gradle 8.14.6, the last 8.x release, has none of the 9.x rows (not run here); its upgrade command in the release notes is ./gradlew wrapper --gradle-version=8.14.6 && ./gradlew wrapper. Since 9.0, wrapper clients still start on JVM 8 while the build itself needs a JVM 17 or newer; see the compatibility page.

Source: Gradle 2.4 release notes: wrapper version from the command line, Gradle 9.4.0 release notes and Gradle 9.5.0 release notes, Gradle 8.14.6 release notes: upgrade instructions

The cross-tool view of repositories, mirrors and credentials is on Repositories & Publishing Across Tools, and the choice of tool on Comparing Ant, Maven & Gradle.

The book Gradle in Action (Gradle 1.7) introduces the wrapper in its chapter 3. It is still the right idea, but its mechanics have changed:

The corrections for the rest of that chapter, such as the Java plugin and its configurations, are on Java Projects.