// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[installation]]
= Installing Gradle
:keywords: install

If all you want to do is run an existing Gradle project, then you don't need to install Gradle if the build uses the <<gradle_wrapper#gradle_wrapper,Gradle Wrapper>>.

If you're **starting a new project from scratch** (especially as a CLI user without an IDE), you'll need to install Gradle first, then use `gradle init` to bootstrap your project with the Gradle Wrapper.
Once the Wrapper is set up, you and your team can use `./gradlew` instead of the installed Gradle version.

[[gs:installation]]
== Gradle Installation

The Gradle Wrapper is identifiable by the presence of the `gradlew` or `gradlew.bat` files in the root of the project:

[source,text,subs=+macros]
----
.   // <1>
├── gradle
│   └── wrapper // <2>
├── gradlew         // <3>
├── gradlew.bat     // <3>
└── ⋮
----
<1> Project root directory.
<2> <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>>.
<3> Scripts for executing Gradle builds.

If the `gradlew` or `gradlew.bat` files are already present in your project, *you do not need to install Gradle*.
But you need to make sure your system <<installation#sec:prerequisites,satisfies Gradle's prerequisites>>.

You can follow the steps in the <<upgrading_version_9.adoc#upgrading_version_9,Upgrading Gradle section>> if you want to update the Gradle version for your project.
Please use the <<gradle_wrapper.adoc#sec:upgrading_wrapper,Gradle Wrapper>> to upgrade Gradle.

Android Studio comes with a working installation of Gradle, so you *don't need to install Gradle separately when only working within that IDE*.

If you do not meet the criteria above and decide to install Gradle on your machine, first check if Gradle is already installed by running `gradle -v` in your terminal.
If the command does not return anything, then Gradle is not installed, and you can follow the instructions below.

You can install Gradle Build Tool on Linux, macOS, or Windows.
The installation can be done manually or using a package manager like https://sdkman.io/[SDKMAN!] or https://brew.sh/[Homebrew].

You can find all Gradle releases and their checksums on the link:{website}/releases[releases page].

[[sec:prerequisites]]
== Prerequisites

Gradle runs on all major operating systems. It requires link:{jdkDownloadUrl}[Java Development Kit] (JDK) version {minJdkVersion} or higher to run. You can check the <<compatibility.adoc#compatibility,compatibility matrix>> for more information.

To check, run `java -version`:

[source,bash]
----
$ java -version
----
[source,text]
----
openjdk version "17.0.6" 2023-01-17
OpenJDK Runtime Environment Temurin-17.0.6+10 (build 17.0.6+10)
OpenJDK 64-Bit Server VM Temurin-17.0.6+10 (build 17.0.6+10, mixed mode)
----

Gradle uses the JDK it finds in your path, the JDK used by your IDE, or the <<gradle_daemon#sec:configuring_daemon_jvm,JDK specified in your project>>.

In this example, the $PATH points to JDK17:

[source,bash]
----
$ echo $PATH
----
[source,text]
----
/opt/homebrew/opt/openjdk@17/bin
----

You can also set the `JAVA_HOME` environment variable to point to a specific JDK installation directory.
This is especially useful when multiple JDKs are installed:

[source,shell]
----
$ echo %JAVA_HOME%
----
[source,text]
----
C:\Program Files\Java\jdk17.0_6
----

[source,bash]
----
$ echo $JAVA_HOME
----
[source,text]
----
/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
----

Gradle supports link:https://kotlinlang.org/[Kotlin] and link:https://groovy-lang.org/[Groovy] as the main build languages.
Gradle ships with its own Kotlin and Groovy libraries, therefore they do not need to be installed.
Existing installations are ignored by Gradle.

<<compatibility.adoc#compatibility, See the full compatibility notes for Java, Groovy, Kotlin, and Android.>>

[[linux_installation]]
== Linux installation

.Installing with a package manager
[%collapsible]
=====

link:http://sdkman.io[SDKMAN!] is a tool for managing parallel versions of multiple Software Development Kits on most Unix-like systems (macOS, Linux, Cygwin, Solaris and FreeBSD).
Gradle is deployed and maintained by SDKMAN!:

[source,bash]
----
$ sdk install gradle
----

Other package managers are available, but the version of Gradle distributed by them is not controlled by Gradle, Inc.
Linux package managers may distribute a modified version of Gradle that is incompatible or incomplete when compared to the official version.

=====

.Installing manually
[%collapsible]
=====

**Step 1 - link:{website}/releases[Download] the latest Gradle distribution**

The distribution ZIP file comes in two flavors:

- Binary-only (bin)
- Complete (all) with docs and sources

We recommend downloading the bin file; it is a smaller file that is quick to download (and the latest documentation is available online).

**Step 2 - Unpack the distribution**

Unzip the distribution zip file in the directory of your choosing, e.g.:

[source,bash,subs="attributes"]
----
$ mkdir /opt/gradle
$ unzip -d /opt/gradle gradle-{gradleVersion}-bin.zip
$ ls /opt/gradle/gradle-{gradleVersion}
----
[source,text]
----
LICENSE  NOTICE  bin  README  init.d  lib  media
----

[[sec:linux_macos_users_2]]

**Step 3 - Configure your system environment**

To install Gradle, the path to the unpacked files needs to be in your Path.
Configure your `PATH` environment variable to include the `bin` directory of the unzipped distribution, e.g.:

[source,bash,subs="attributes"]
----
$ export PATH=$PATH:/opt/gradle/gradle-{gradleVersion}/bin
----

Alternatively, you could also add the environment variable `GRADLE_HOME` and point this to the unzipped distribution.
Instead of adding a specific version of Gradle to your `PATH`, you can add `$GRADLE_HOME/bin` to your `PATH`.
When upgrading to a different version of Gradle, simply change the `GRADLE_HOME` environment variable.

[source,bash,subs="attributes"]
----
$ export GRADLE_HOME=/opt/gradle/gradle-{gradleVersion}
$ export PATH=${GRADLE_HOME}/bin:${PATH}
----

=====

[[macos_installation]]
== macOS installation

.Installing with a package manager
[%collapsible]
=====

link:http://sdkman.io[SDKMAN!] is a tool for managing parallel versions of multiple Software Development Kits on most Unix-like systems (macOS, Linux, Cygwin, Solaris and FreeBSD).
Gradle is deployed and maintained by SDKMAN!:

[source,bash]
----
$ sdk install gradle
----

Using link:http://brew.sh[Homebrew]:

[source,bash]
----
$ brew install gradle
----

Using link:https://www.macports.org[MacPorts]:

[source,bash]
----
$ sudo port install gradle
----

Other package managers are available, but the version of Gradle distributed by them is not controlled by Gradle, Inc.

=====

.Installing manually
[%collapsible]
=====

**Step 1 - link:{website}/releases[Download] the latest Gradle distribution**

The distribution ZIP file comes in two flavors:

- Binary-only (bin)
- Complete (all) with docs and sources

We recommend downloading the bin file; it is a smaller file that is quick to download (and the latest documentation is available online).

**Step 2 - Unpack the distribution**

Unzip the distribution zip file in the directory of your choosing, e.g.:

[source,bash,subs="attributes"]
----
$ mkdir /usr/local/gradle
$ unzip gradle-{gradleVersion}-bin.zip -d /usr/local/gradle
$ ls /usr/local/gradle/gradle-{gradleVersion}
----
[source,text]
----
LICENSE	NOTICE	README	bin	init.d	lib
----

**Step 3 - Configure your system environment**

To install Gradle, the path to the unpacked files needs to be in your Path.
Configure your `PATH` environment variable to include the `bin` directory of the unzipped distribution, e.g.:

[source,bash,subs="attributes"]
----
$ export PATH=$PATH:/usr/local/gradle/gradle-{gradleVersion}/bin
----

Alternatively, you could also add the environment variable `GRADLE_HOME` and point this to the unzipped distribution.
Instead of adding a specific version of Gradle to your `PATH`, you can add `$GRADLE_HOME/bin` to your `PATH`.
When upgrading to a different version of Gradle, simply change the `GRADLE_HOME` environment variable.

It's a good idea to edit `.bash_profile` in your home directory to add `GRADLE_HOME` variable:

[source,bash,subs="attributes"]
----
$ export GRADLE_HOME=/usr/local/gradle/gradle-{gradleVersion}
$ export PATH=$GRADLE_HOME/bin:$PATH
----

=====

[[windows_installation]]
== Windows installation

.Installing with a package manager
[%collapsible]
=====

link:http://sdkman.io[SDKMAN!] is available for Windows through WSL (Windows Subsystem for Linux):

[source,bash]
----
$ sdk install gradle
----

Using link:https://chocolatey.org/[Chocolatey]:

[source,powershell]
----
> choco install gradle
----

Using link:https://scoop.sh/[Scoop]:

[source,powershell]
----
> scoop install gradle
----

Using link:https://learn.microsoft.com/en-us/windows/package-manager/winget/[winget] (Windows Package Manager):

[source,powershell]
----
> winget install Gradle.Gradle
----

Other package managers are available, but the version of Gradle distributed by them is not controlled by Gradle, Inc.

=====

.Installing manually
[%collapsible]
=====

**Step 1 - link:{website}/releases[Download] the latest Gradle distribution**

The distribution ZIP file comes in two flavors:

- Binary-only (bin)
- Complete (all) with docs and sources

We recommend downloading the bin file.

**Step 2 - Unpack the distribution**

Create a new directory `C:\Gradle` with **File Explorer**.

Open a second **File Explorer** window and go to the directory where the Gradle distribution was downloaded. Double-click the ZIP archive to expose the content.
Drag the content folder `gradle-{gradleVersion}` to your newly created `C:\Gradle` folder.

Alternatively, you can unpack the Gradle distribution ZIP into `C:\Gradle` using the archiver tool of your choice.

**Step 3 - Configure your system environment**

To install Gradle, the path to the unpacked files needs to be in your Path.

In **File Explorer** right-click on the `This PC` (or `Computer`) icon, then click `Properties` -> `Advanced System Settings` -> `Environmental Variables`.

Under `System Variables` select `Path`, then click `Edit`.
Add an entry for `C:\Gradle\gradle-{gradleVersion}\bin`.
Click `OK` to save.

Alternatively, you can add the environment variable `GRADLE_HOME` and point this to the unzipped distribution.
Instead of adding a specific version of Gradle to your `Path`, you can add `__%GRADLE_HOME%__\bin` to your `Path`.
When upgrading to a different version of Gradle, just change the `GRADLE_HOME` environment variable.

=====

[[sec:running_and_testing_your_installation]]
== Verify the installation

Open a console (or a Windows command prompt) and run `gradle -v` to run gradle and display the version, e.g.:

[source,bash,subs="attributes"]
----
$ gradle -v
----
[source,text]
----
------------------------------------------------------------
Gradle 9.0.0
------------------------------------------------------------

Build time:    2025-07-17 12:48:00 UTC
Revision:      2db9560bb68c367a265b10516c856c840f9bed8d

Kotlin:        2.2.0
Groovy:        4.0.28
Ant:           Apache Ant(TM) version 1.10.15 compiled on August 25 2024
Launcher JVM:  17.0.11 (Amazon.com Inc. 17.0.11+9-LTS)
Daemon JVM:    Compatible with Java 17, any vendor, nativeImageCapable=false (from gradle/gradle-daemon-jvm.properties)
OS:            Mac OS X 14.7.4 aarch64
----

You can verify the integrity of the Gradle distribution by downloading the SHA-256 file (available from the link:{website}/releases[releases page]) and following these <<gradle_wrapper.adoc#sec:verification,verification instructions>>.

[[sec:bootstrapping_new_gradle_projects]]
== Bootstrapping new projects

Once Gradle is installed, run `gradle init` to bootstrap a new Gradle project.
This is particularly useful for CLI users starting a project from scratch without an IDE.

The `init` task generates a build script, a settings file, the <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>> files, and (for non-`basic` project types) sample source code.
Once the Wrapper is committed, you and your team can build the project with `./gradlew` (or `gradlew.bat` on Windows).

For an interactive walkthrough, run:

[source,bash]
----
$ gradle init
----

Gradle asks you to pick a project type (Application, Library, Gradle plugin, or a basic build structure), a build script DSL (Kotlin or Groovy), a test framework, and project and package names.

For non-interactive use, pass the options directly:

[source,bash]
----
$ gradle init --type java-application --dsl kotlin --test-framework junit-jupiter --package com.example --project-name my-app
----

See the <<build_init_plugin.adoc#build_init_plugin,Build Init Plugin>> documentation for the full list of project types, flags, and options.
