Install Gradle on macOS

Introduction

This chapter installs Gradle on macOS for local development and for running gradle wrapper when you start new projects. Install JDK 21 first. Day-to-day work on shared repos should use ./gradlew so everyone uses the same Gradle version; a Homebrew or SDKMAN install is your personal bootstrap tool.

Prerequisites

macOS with terminal access (zsh default on modern Macs)
JDK 21 installed (macOS Java install)
Internet access
Optional: Homebrew or SDKMAN

Verify JDK 21

bash

java -version
javac -version

If the version is not 21:

bash

# Point JAVA_HOME to JDK 21 (Apple Silicon / Intel paths may differ)
export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Add that line to ~/.zshrc if needed, then:

bash

source ~/.zshrc
java -version

Option A: Homebrew (Simple)

bash

# Install Gradle
brew install gradle
 
# Verify
gradle -version

Check that the output lists Java: 21 (or JVM 21). Homebrew upgrades:

bash

brew upgrade gradle

Tip

Avoid Ancient System Tools

Do not rely on random old Gradle binaries that might appear on PATH from legacy installs. After Homebrew, run which gradle—it should point under /opt/homebrew or /usr/local.

Option B: SDKMAN (Multiple Versions)

SDKMAN shines when you maintain several Gradle versions for different clients.

bash

Switch later:

bash

sdk use gradle 8.10

Option C: Manual ZIP Install

Download the binary-only ZIP from gradle.org/releases
Extract:

bash

# Example location
sudo mkdir -p /opt/gradle
sudo tar -xzf gradle-8.12.1-bin.zip -C /opt/gradle

Add to ~/.zshrc:

bash

export GRADLE_HOME=/opt/gradle/gradle-8.12.1
export PATH="$GRADLE_HOME/bin:$PATH"

Reload and verify:

bash

source ~/.zshrc
gradle -version

Bootstrap Wrapper in an Empty Directory

bash

mkdir ~/hello-gradle && cd ~/hello-gradle
gradle wrapper --gradle-version 8.12.1
ls -la
./gradlew -version

Commit gradlew, gradlew.bat, and gradle/wrapper/ to git—teammates need no global Gradle.

Common macOS Issues

Symptom	Cause	Fix
`gradle: command not found`	PATH not loaded	`source ~/.zshrc`; check `which gradle`
Java 17 or 8 in `gradle -version`	Wrong `JAVA_HOME`	`/usr/libexec/java_home -v 21`
Permission denied on `gradlew`	File not executable	`chmod +x gradlew`
Rosetta / arch confusion	Mixed ARM/x86 JDK	Install ARM-native JDK 21 for Apple Silicon

Uninstall

Method	Command
Homebrew	`brew uninstall gradle`
SDKMAN	`sdk rm gradle 8.12.1`
Manual	Remove folder and `GRADLE_HOME` lines from `~/.zshrc`

FAQ

Homebrew vs SDKMAN?

Homebrew for one current Gradle. SDKMAN when you juggle versions often.

Do Android developers use this Gradle?

Android projects use the Android Gradle Plugin with a project Wrapper. The same gradle -version skills apply; Android Studio manages much of the sync UI.

Must macOS match Windows Gradle version?

Per-repo Wrapper version should match across OS. Global installs can differ; ./gradlew is the source of truth.

What comes next?

Linux install if you also use Linux, then IntelliJ and your first Gradle project in later chapters.