Gradle: Installation

Every release is published as two ZIP files. The binary-only distribution (-bin) contains the program; the complete one (-all) adds the documentation and the sources. The official recommendation is the -bin file: it is smaller and quick to download, and the documentation is online. For 9.8.1 the -bin archive is 151,620,101 bytes (about 145 MB) and unpacks to 165 MB. The same choice, -bin or -all, returns for the wrapper, which downloads one of these two files; why -bin is the better default is in Gradle Wrapper.

Gradle publishes the list of releases on https://gradle.org/releases/ and the same information in a small JSON document that tools use. The "current" endpoint is a handy way to ask which release is current, where its archive is, and which SHA-256 it should have; it is metadata, not a download of the distribution:

The listing is cut after publicationSlot (an ellipsis line marks the cut). The fields activeRc, snapshot and nightly exist because the same family of endpoints also describes release candidates and nightly builds.

Source: Gradle: Releases

Source: Gradle: Install Gradle

Gradle publishes a SHA-256 checksum for every distribution and for every gradle-wrapper.jar on its release-checksums page, and next to the file itself (a .sha256 file that services.gradle.org answers with a redirect to downloads.gradle.org). A checksum protects you from a damaged or substituted download only as far as you trust the channel the checksum came from: fetch it from gradle.org over HTTPS, not from the place you got the ZIP. Gradle also publishes a detached PGP signature (gradle-9.8.1-bin.zip.asc is served next to the archive, and the manual says Gradle publishes PGP signatures for all distribution artifacts), as Apache does for Ant and Maven; checking it needs Gradle’s public key, and that check was not run here. The checksum file holds the bare hexadecimal value and no file name, so the shasum -c form needs the name added to the line. The first check below is the real archive; the second appends one byte to a copy of it:

The value is the one in the JSON above and the one on the release-checksums page; it is also the distributionSha256Sum that a wrapper for 9.8.1 pins. On Linux use sha256sum -c in place of shasum -a 256 -c; on Windows certutil -hashfile gradle-9.8.1-bin.zip SHA256 prints the digest to compare by eye (not run here). Checking the wrapper JAR, validating the wrapper on CI and the other supply-chain controls are in Supply-Chain Security; the wrapper properties that pin the checksum are in Gradle Wrapper.

Source: Gradle: release checksums

Source: Gradle: Installing Gradle, Verify the installation

Source: Gradle Wrapper: Verifying the Gradle Wrapper JAR with PGP

The official examples unpack into /opt/gradle on Linux and /usr/local/gradle on macOS. Any directory works, and a directory per version (gradle-9.8.1) lets several versions live side by side. The run below unpacked the verified archive into a scratch directory that is shown as /opt/gradle:

The layout is small:

There is no conf directory and no global settings.xml-style file as in Maven: the configuration lives in the Gradle User Home and in the projects, and the installation only contributes the two optional files described in Files in the installation directory.

Source: Gradle User Manual: Installing Gradle, Linux installation, macOS installation

Put the bin directory on the PATH:

The official page offers an alternative: define GRADLE_HOME and put $GRADLE_HOME/bin on the PATH, so that upgrading means changing one variable.

Put the lines in the shell start-up file (.bash_profile, .zshrc, /etc/profile.d/) so that every new shell has them. On Windows the official steps are the System Properties dialog (Advanced System Settings, Environment Variables, edit Path, add C:\Gradle\gradle-9.8.1\bin) or the same GRADLE_HOME and %GRADLE_HOME%\bin pair (not run here).

GRADLE_HOME is only a convenience for building the PATH: neither launcher script reads it. The POSIX script finds its own directory from the path it was started with, following symbolic links, and the Windows batch file does the same (a search for GRADLE_HOME in bin/gradle.bat finds nothing; the batch file was not run). The run below sets GRADLE_HOME to a directory that does not exist and still gets the version, and starts the script through a symbolic link in another directory:

This is why advice that tells you to set GRADLE_HOME as a requirement is out of date, and why the PATH entry (or a symbolic link such as /usr/local/bin/gradle) is all that matters. The GRADLE_HOME that Gradle documents as a configuration location is the installation directory itself; see Files in the installation directory.

Source: Gradle: Installing Gradle, Linux installation

Source: Gradle: Installing Gradle, macOS installation

Source: Gradle: Installing Gradle, Windows installation

The 248-line bin/gradle script (wc -l on the 9.8.1 distribution) is a small POSIX program; reading it explains most installation problems. In order, it resolves its own directory (APP_HOME, through symbolic links), then picks the Java: $JAVA_HOME/bin/java when JAVA_HOME is set (and fails with an error if it is not a directory with a java in it), otherwise the java found on the PATH (and fails if there is none). It then builds the command line of the client JVM from three sources, in this order: the script’s defaults, JAVA_OPTS and GRADLE_OPTS. The defaults are -Xmx64m -Xms64m and the instrumentation agent, which is a lightweight client: the real work happens in the daemon, a separate JVM that the client starts or reuses, whose options are not these. The last line runs java -jar lib/gradle-gradle-cli-main-9.8.1.jar with the arguments you gave.

The consequence people trip over: JAVA_OPTS and GRADLE_OPTS set the options of the small client JVM; the daemon’s heap is org.gradle.jvmargs in gradle.properties (default -Xmx512m; see Build Environment & Properties), and which JVM the daemon uses is the subject of Gradle Daemon. The environment variables Gradle reads are listed in the build-environment page of the manual.

Source: Gradle: Build Environment, Environment variables

Source: Gradle: Gradle Daemon, the client and the daemon

gradle init with no options is meant for a terminal: Gradle lists the project types and asks about the DSL, the test framework and the names. When there is no interactive console, Gradle does not ask; it uses what it can infer. Running it in an empty directory with its input piped from a script and --console=plain, which is how a CI job or a script would run it, shows what that gives:

The piped answers were ignored (no questions were printed) and the result is the basic type with the Kotlin DSL: an empty build script, a settings file naming the project after the directory, the wrapper, an empty version catalog and a gradle.properties whose only content is org.gradle.configuration-cache=true. So a scripted gradle init must pass its choices as options; the interactive questions were not exercised here, because they need a terminal.

Two details of the generated files are worth knowing. The wrapper properties come out pointing at the official distribution:

There is no distributionSha256Sum: init does not pin the checksum, so adding it (gradle wrapper --gradle-distribution-sha256-sum=…​) is the first hardening step; see Gradle Wrapper. And gradle.properties already turns the configuration cache on, the preferred mode since Gradle 9.0, so projects bootstrapped by 9.8.1 start with it enabled (it is still off by default for projects that do not set it; Gradle 10 is announced to turn it on).

Source: Build Init Plugin: Sample usage

The running scenario is a multi-module Java build (a model, an engine and a command-line interface). gradle init cannot produce that exact layout, but the Java application type with --split-project produces the same shape (an application that depends on libraries) and is the way the official tutorial starts. Non-interactive, with every choice given:

What was generated, with the explanatory comments left out for brevity:

Several things here differ from the conventions this section recommends, and are worth noticing because gradle init is where most people meet Gradle first. The shared build logic lives in buildSrc, the older of the two ways to share it; the recommended place is an included build named build-logic (see Convention Plugins & Sharing Build Logic). Repositories are declared in the convention plugin, not once in the settings file, and the dependency versions are in the convention plugin (a constraint, and the JUnit coordinate) while the version catalog is empty. The toolchain is the --java-version you gave (26 here), and the settings file applies the Foojay resolver so that a missing JDK can be downloaded for the toolchain. The versions in the templates (JUnit 6.0.1, commons-text 1.14.0, the Foojay plugin 1.0.0) are fixed inside Gradle 9.8.1 and are not refreshed at generation time, so they may be behind the latest releases: update them after generating. The next pages of the section rework this layout into the conventions used for tidepool.

The generated project builds with the installed Gradle (the first run downloaded JUnit and commons-text from Maven Central). It was built with --configuration-cache, and is compatible with it: the first build stored an entry and the later one reused it.

Only the last lines of the first build are shown (the ellipsis line marks the cut), then the output of gradle run --quiet, then the last lines of the repeat build. The first build executed 22 tasks (a first-ever run is slower, because it also downloads the dependencies and the build-logic plugins), the repeat build found everything up to date and reused the cache entry, and run printed Hello World!. Running the generated ./gradlew instead would use the wrapper properties above, which download the 9.8.1 distribution from services.gradle.org; it was not run here, because the installed 9.8.1 is the same version and no second download was made.

Source: Gradle User Manual: Build Init Plugin, java-application build type, Options

Only --dsl groovy changes; everything else is the same command:

The Groovy convention plugins live in src/main/groovy instead of src/main/kotlin. The same files in Groovy syntax (single quotes and no parentheses for method calls are the visible differences):

This project was built and run too, with --configuration-cache and the installed Gradle: the build succeeded (20 actionable tasks executed), run printed Hello World! and the repeat build reported 13 up-to-date tasks and Configuration cache entry reused. The differences between the DSLs are the subject of Kotlin DSL and Groovy DSL & Migrating to Kotlin.

Source: Gradle User Manual: Build Init Plugin, options

Without --split-project the sample is one subproject. Even then the build has a subproject, named app, and a root project with no code (Kotlin DSL; the Groovy output has the same shape):

Here the generated build uses a version catalog (libs.guava, libs.junit.jupiter), the layout the section recommends, and declares the repository in the subproject. (The catalog is shown as plain text because the documentation viewer has no TOML highlighting.) Version catalogs are covered in Version Catalogs.

--use-defaults fills every option not given with its default and does not prompt. With only a type and a directory:

The default Java version of the generated toolchain is 21 in Gradle 9.8.1, not the JDK that runs Gradle (26 here), so the build will need JDK 21 or let the Foojay resolver download one. Pass --java-version to choose.

Source: Gradle User Manual: Build Init Plugin, options, The --java-version option

gradle init refuses to write over a directory that already has files, and rejects unknown types. Both messages are as printed (the scratch path is shortened to <scratch>):

--overwrite replaces existing files, which is the reason to run init only in an empty directory or in a Git working tree where you can see what changed.

Source: Gradle User Manual: Build Init Plugin, build init types

In a directory with a pom.xml, gradle init infers the pom type and converts the effective POM (so inheritance, dependency management and properties are resolved) to Gradle files; single and multi-module builds are supported. The manual states the limits: Maven and Gradle differ fundamentally, so the result "should be considered a starting point for further refinement". Compile-scope dependencies become api dependencies of the java-library plugin, because Maven exposes them to consumers, and the manual encourages moving as many as possible to implementation. Plain http repository URLs are handled according to --insecure-protocol. The conversion is walked through, with tidepool’s Maven build, in Migrating from Maven; the comparison of the three tools' migration paths is in Migrating Between Tools. The conversion was not run on this page.

Source: Build Init Plugin: pom build type (Maven conversion)

Source: Build Init Plugin: The --insecure-protocol option

Source: Build Init Plugin: The --java-version option

Source: Gradle tutorial: Initializing the project