Installing Java on Mac — OpenJDK 21 Setup Guide

2 minute read

In this chapter, you’ll install the Java Development Kit (JDK) 21 on macOS. The recommended method is Homebrew — it’s fast, clean, and easy to manage.

Step 1: Install Homebrew (if not already installed)

Open Terminal (Cmd + Space, type “Terminal”) and run:

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Verify Homebrew:

$ brew --version

Step 2: Install OpenJDK 21

$ brew install openjdk@21

macOS needs a symlink so the system can find Java:

$ sudo ln -sfn $(brew --prefix openjdk@21)/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk

Step 4: Set JAVA_HOME

Add to your ~/.zshrc (macOS default shell is zsh):

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

Reload:

$ source ~/.zshrc

Step 5: Verify

$ java -version

Expected output:

openjdk version "21.0.2" 2024-01-16
OpenJDK Runtime Environment Homebrew (build 21.0.2)
OpenJDK 64-Bit Server VM Homebrew (build 21.0.2, mixed mode, sharing)

$ javac -version

Expected output:

javac 21.0.2

$ echo $JAVA_HOME
/opt/homebrew/Cellar/openjdk@21/21.0.2/libexec/openjdk.jdk/Contents/Home

Method 2: Download from Adoptium

  1. Go to https://adoptium.net/
  2. Download the macOS .pkg installer for Java 21
  3. Run the installer
  4. Set JAVA_HOME as shown above

Apple Silicon (M1/M2/M3/M4) vs Intel

Both Homebrew and Adoptium provide native builds for Apple Silicon. No extra steps needed.

Chip Architecture Homebrew Prefix
Apple Silicon (M1+) aarch64 /opt/homebrew/
Intel x86_64 /usr/local/

To check your architecture:

$ uname -m

Output: arm64 (Apple Silicon) or x86_64 (Intel).

Managing Multiple Java Versions with jEnv

If you need multiple Java versions, jEnv makes switching easy:

Install jEnv

$ brew install jenv

Add to ~/.zshrc:

export PATH="$HOME/.jenv/bin:$PATH"
eval "$(jenv init -)"

Reload:

$ source ~/.zshrc

Add Java Versions

$ jenv add $(/usr/libexec/java_home -v 21)
$ jenv add $(/usr/libexec/java_home -v 17)  # if installed

Switch Versions

$ jenv global 21       # Set default to Java 21
$ jenv local 17        # Set Java 17 for current directory only
$ jenv version         # Show active version

Test with Hello World

$ mkdir ~/java-projects && cd ~/java-projects
$ cat > HelloWorld.java << 'EOF'
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World! Java is working on Mac!");
    }
}
EOF
$ javac HelloWorld.java
$ java HelloWorld

Expected output:

Hello, World! Java is working on Mac!

Common Issues and Fixes

Problem Solution
java -version shows Apple stub Install JDK via Homebrew or Adoptium — macOS ships with a placeholder that prompts installation
JAVA_HOME not set Add the export line to ~/.zshrc and run source ~/.zshrc
Homebrew on wrong path Apple Silicon uses /opt/homebrew, Intel uses /usr/local. Verify with brew --prefix
Permission denied on symlink Use sudo for the ln -sfn command

Summary

Step Command
Install brew install openjdk@21
Symlink sudo ln -sfn $(brew --prefix openjdk@21)/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk
Set JAVA_HOME Add export JAVA_HOME=$(/usr/libexec/java_home -v 21) to ~/.zshrc
Verify java -version, javac -version, echo $JAVA_HOME
Test Compile and run HelloWorld.java

What’s Next?

Updated:

You may also enjoy