Install Java on macOS

Introduction

This chapter shows you how to install JDK 21 (LTS) on macOS for learning and development. You will choose a reliable installation method, configure JAVA_HOME, and verify both java and javac. macOS may ship an old Java stub or none at all—do not rely on it for this tutorial.

Prerequisites

  • A Mac running a recent macOS version (Ventura, Sonoma, or newer recommended)
  • Basic terminal knowledge (cd, ls, running commands)
  • Internet access for Homebrew or installer downloads
  • If you use Homebrew: brew.sh installed

Choose the Right Java Version

Use JDK 21 (LTS) unless your team or course requires another version. Match shared projects to your team’s JDK. Avoid installing Java 8 “by default” for new learning unless you have a specific compatibility need.

You need a JDK (includes javac), not a runtime-only package. See Windows install for JDK vs JRE if that distinction is new to you.

Choose an Installation Method

MethodBest for
Homebrew + Temurin caskMost developers; easy upgrades
Homebrew openjdk@21Prefer formula-based installs
Official .pkg installerTeams that standardize on Adoptium/Oracle packages

Warning

Do not use the macOS system Java stub for development. It may be missing, outdated, or misleading. Install JDK 21 explicitly and verify with java -version and javac -version.

Option A: Temurin cask (simplest)

bash
# Install Eclipse Temurin JDK 21
brew install --cask temurin@21
 
# Verify runtime and compiler
java -version
javac -version

Option B: openjdk@21 formula

bash
brew update
brew install openjdk@21
 
# Add to PATH and JAVA_HOME (Apple Silicon — Homebrew prefix /opt/homebrew)
echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zshrc
echo 'export JAVA_HOME="/opt/homebrew/opt/openjdk@21"' >> ~/.zshrc
 
# On Intel Macs, Homebrew often uses /usr/local instead:
# export PATH="/usr/local/opt/openjdk@21/bin:$PATH"
# export JAVA_HOME="/usr/local/opt/openjdk@21"
 
source ~/.zshrc
 
java -version
javac -version

Tip

Best Practice

After changing PATH or JAVA_HOME, open a new terminal tab or run source ~/.zshrc before verifying versions.

Install JDK 21 from a .pkg Installer (Alternative)

  1. Download Temurin 21 (LTS) for macOS from adoptium.net.
  2. Run the .pkg installer and complete setup.
  3. Open a new terminal and verify:
bash
java -version
javac -version
/usr/libexec/java_home -V

The last command lists installed JDKs macOS can see—useful when multiple versions exist.

Set JAVA_HOME on macOS

Many tools (Maven, Gradle, IDEs) read JAVA_HOME.

bash
# Print the path Homebrew reports for openjdk@21 (if you used that formula)
brew --prefix openjdk@21
 
# Or ask macOS which JDK to use (works after .pkg installs too)
/usr/libexec/java_home -v 21

Add to ~/.zshrc (adjust path to match your install):

bash
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH="$JAVA_HOME/bin:$PATH"

Verify Installation

bash
java -version
javac -version
echo $JAVA_HOME
which java
which javac

Expected outcome:

  • Both commands report 21.x
  • which java points to your installed JDK, not a broken stub

Common Issues and Fixes

java opens a dialog asking to install legacy Java

  • Cause: No proper JDK on the system; macOS is prompting for an old Apple Java plugin workflow.
  • Fix: Install JDK 21 with Homebrew or Adoptium, then verify in Terminal—not via the browser plugin prompt.

java works but javac is not found

  • Cause: Only a JRE-like runtime is available, or PATH is incomplete.
  • Fix: Install a full JDK 21 and ensure $JAVA_HOME/bin is on PATH.

Wrong version (e.g. Java 8 or 11)

  • Cause: Another JDK is earlier on PATH.
  • Fix: Run /usr/libexec/java_home -V, set JAVA_HOME to 21 explicitly, and put $JAVA_HOME/bin first in PATH.

What’s Next

Linux installation is covered in Install Java on Linux. When your JDK is ready on any OS, continue to Write and Run Hello World using only the terminal.

FAQ

Should I use Homebrew or the .pkg installer?

Homebrew is easier to upgrade and reproduce across machines. The .pkg installer is fine when your team standardizes on it or you prefer GUI setup.

Is the Java on my Mac enough for this course?

Usually no. Install JDK 21 explicitly and verify javac -version.

Do I need to install Java separately for IntelliJ IDEA?

IntelliJ can use its bundled runtime for the IDE itself, but your projects should use the JDK you installed. You will configure the project SDK in a later chapter.

Can I install multiple Java versions on macOS?

Yes. Use /usr/libexec/java_home -v <version> or tools like SDKMAN (see the Linux chapter) to switch. Prefer per-project JDK settings in your IDE when possible.

Apple Silicon vs Intel: does it matter?

Download the correct architecture (aarch64 vs x64) from Adoptium. Homebrew on Apple Silicon uses /opt/homebrew; on Intel, /usr/local.