How to Install Java on macOS: A Step-by-Step Guide for Beginners

Java is a versatile programming language used for developing applications ranging from web services to mobile apps. To code or run Java programs on macOS, you need to install the Java Development Kit (JDK), which provides the tools to write, compile, and execute Java code. For beginners, setting up Java on macOS is a crucial first step to begin your programming journey. This blog offers a detailed, step-by-step guide to installing Java on macOS, covering the JDK installation, environment variable configuration, and verification process. With clear explanations and practical examples, you’ll be ready to run your first Java program, like the Hello World program, in no time. Let’s get started with installing Java on macOS and setting up your development environment!

Why Install Java on macOS?

macOS is a popular choice among developers for its Unix-based architecture, stability, and integration with development tools. Installing Java on macOS enables you to:

  • Develop Java Applications: Write, compile, and debug code using the JDK’s tools.
  • Run Java Software: Execute Java-based applications, such as IDEs, servers, or desktop tools, using the Java Runtime Environment (JRE).
  • Explore Java Frameworks: Work with frameworks like Spring, JavaFX, or Apache Spark for enterprise, desktop, or data processing applications.
  • Learn Programming: Practice Java fundamentals, from data types to object-oriented programming.

This guide focuses on installing OpenJDK, a free and open-source implementation of the JDK, ideal for most development needs. For a broader overview of Java installation across platforms, see the Java Installation Guide.

Understanding Java Components

Before installing, let’s clarify the key components involved:

  • Java Development Kit (JDK): Includes the Java compiler (javac), Java Virtual Machine (JVM), JRE, and development tools for building Java applications.
  • Java Runtime Environment (JRE): Contains the JVM and libraries to run Java programs but lacks development tools. The JDK includes the JRE, so installing the JDK is sufficient for development.
  • JVM: Executes Java bytecode, ensuring platform independence.

For coding, you need the JDK. For a detailed comparison, see JVM vs. JRE vs. JDK.

Choosing a JDK Version

Java releases new versions every six months, with Long-Term Support (LTS) versions receiving updates for years. As of June 8, 2025, Java 21 is the latest LTS version, offering stability and modern features like virtual threads. For beginners, an LTS version like Java 21 is recommended for compatibility and long-term support.

You can choose between:

  • OpenJDK: Free, open-source, and community-maintained. Distributions like Adoptium (Temurin) are reliable and widely used.
  • Oracle JDK: Free for personal use and development, but requires a commercial license for production. OpenJDK is sufficient for most purposes.

This guide uses Adoptium’s Temurin OpenJDK 21 for its ease of installation and open-source nature, but we’ll also cover Homebrew as an alternative.

Prerequisites

Ensure your macOS system is ready:

  • macOS Version: This guide targets macOS Ventura (13), Sonoma (14), or later. Steps are similar for older versions like Mojave (10.14) or Monterey (12).
  • Internet Connection: Required to download the JDK.
  • Administrative Privileges: Needed to install software.
  • Disk Space: At least 500 MB for the JDK, plus space for your projects.
  • Terminal Access: You’ll use the Terminal app (found in Applications > Utilities) for commands.

Installing OpenJDK on macOS Using Adoptium’s Installer

Adoptium provides a user-friendly installer for OpenJDK on macOS. Follow these steps to install Java 21.

Step 1: Download the JDK

  1. Visit the Adoptium website.
  2. Select Temurin 21 (LTS) as the version.
  3. Choose macOS as the operating system and select the appropriate architecture:
    • x64 for Intel-based Macs.
    • aarch64 for Apple Silicon (M1/M2/M3) Macs.

4. Click the Download button for the .pkg file (e.g., OpenJDK21U-jdk_aarch64_mac_hotspot_21.0.1_15.pkg). 5. Save the installer to a known location (e.g., Downloads folder).

Step 2: Run the Installer

  1. Double-click the downloaded .pkg file in Finder to launch the installer.
  2. Follow the installation wizard:
    • Introduction: Click Continue.
    • License: Read and accept the license agreement.
    • Destination Select: Choose the default installation path (e.g., /Library/Java/JavaVirtualMachines/temurin-21.jdk).
    • Installation Type: Click Install to proceed.

3. Enter your admin password when prompted. 4. Wait for the installation to complete, then click Close to exit.

Step 3: Verify the Installation

Open the Terminal (Applications > Utilities > Terminal) and run:

java -version
javac -version

Expected output (for Apple Silicon):

openjdk 21.0.1 2023-10-17
OpenJDK Runtime Environment Temurin-21.0.1+12 (build 21.0.1+12)
OpenJDK 64-Bit Server VM Temurin-21.0.1+12 (build 21.0.1+12, mixed mode)
javac 21.0.1
  • java -version: Verifies the JRE and JVM.
  • javac -version: Confirms the compiler is installed.
  • If both commands show version details, the installation is successful.

Step 4: Troubleshooting Installation

If the commands fail:

  • “command not found”: The JDK may not be in your PATH. Proceed to configure environment variables (below).
  • Installer Failure: Ensure you have admin rights and sufficient disk space. Re-download the installer if corrupted.
  • Wrong Architecture: Verify you downloaded the correct version (x64 for Intel, aarch64 for Apple Silicon).

Alternative: Installing OpenJDK Using Homebrew

Homebrew is a popular package manager for macOS, simplifying Java installation. If you prefer Homebrew or want to manage multiple Java versions easily, follow these steps.

Step 1: Install Homebrew (If Not Already Installed)

Check if Homebrew is installed:

brew --version

If not installed, run:

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

Follow the prompts to complete the installation, then add Homebrew to your PATH (instructions provided during installation).

Step 2: Install OpenJDK 21

  1. Update Homebrew:
brew update
  1. Install OpenJDK 21:
brew install openjdk@21
  • Homebrew installs OpenJDK 21 to /usr/local/Cellar/openjdk@21 (Intel) or /opt/homebrew/Cellar/openjdk@21 (Apple Silicon).

Homebrew may not automatically link the JDK to /usr/local/bin. Link it manually:

sudo ln -sfn /opt/homebrew/Cellar/openjdk@21/*/bin/* /opt/homebrew/bin/

Adjust the path for Intel Macs:

sudo ln -sfn /usr/local/Cellar/openjdk@21/*/bin/* /usr/local/bin/

Step 4: Verify Installation

Run:

java -version
javac -version

Expected output:

openjdk 21.0.1 2023-10-17
OpenJDK Runtime Environment (build 21.0.1+12)
OpenJDK 64-Bit Server VM (build 21.0.1+12, mixed mode)
javac 21.0.1

Step 5: Troubleshooting Homebrew

  • “brew not found”: Ensure Homebrew is installed and added to PATH. Run echo $PATH to check.
  • Version Mismatch: If another Java version is detected, proceed to configure environment variables or manage versions (below).
  • Permission Errors: Use sudo for linking commands or fix permissions with chmod.

Configuring Environment Variables

To run Java commands (java, javac) from any directory and ensure tools like IDEs recognize the JDK, configure JAVA_HOME and update your PATH. This is optional but recommended.

Step 1: Find the JDK Path

The Adoptium installer typically places the JDK at:

/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

For Homebrew, find the path:

ls /opt/homebrew/Cellar/openjdk@21

or

ls /usr/local/Cellar/openjdk@21

Example path: /opt/homebrew/Cellar/openjdk@21/21.0.1/libexec/openjdk.jdk/Contents/Home.

Alternatively, use:

/usr/libexec/java_home -v 21

This outputs the JDK path (e.g., /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home).

Step 2: Set JAVA_HOME

macOS uses shell configuration files like ~/.zshrc (default since macOS Catalina) or ~/.bashrc (for Bash). Configure JAVA_HOME: 1. Open the appropriate file:

nano ~/.zshrc
  1. Add the following line (replace the path with your JDK’s path):
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
  • This dynamically sets JAVA_HOME to the Java 21 installation.
  • Alternatively, hardcode the path:
  • export JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

3. Add the JDK’s bin to PATH:

export PATH=$JAVA_HOME/bin:$PATH
  1. Save and exit (Ctrl+O, Enter, Ctrl+X).
  2. Apply changes:
source ~/.zshrc

Step 3: Verify Configuration

Check JAVA_HOME:

echo $JAVA_HOME

Expected output:

/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

Verify commands:

which java
which javac

Output:

/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin/java
/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin/javac

Run version checks again:

java -version
javac -version

Step 4: Troubleshooting Environment Variables

  • Empty JAVA_HOME: Ensure the export line was added correctly and source ~/.zshrc was run.
  • “command not found”: Check that $JAVA_HOME/bin is in PATH. Re-edit ~/.zshrc if needed.
  • Wrong JDK Path: Use /usr/libexec/java_home -v 21 to confirm the path and update ~/.zshrc.

Managing Multiple Java Versions

If you have multiple JDKs installed (e.g., Java 17 and 21), use /usr/libexec/java_home or a version manager like SDKMAN!.

Using /usr/libexec/java_home

List installed JDKs:

/usr/libexec/java_home -V

Example output:

Matching Java Virtual Machines (2):
    21.0.1, aarch64: "OpenJDK 21.0.1" /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home
    17.0.5, aarch64: "OpenJDK 17.0.5" /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home

Set a specific version:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Apply temporarily or add to ~/.zshrc.

Using SDKMAN!

Install SDKMAN! for easier version management:

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

Install Java 21:

sdk install java 21.0.1-tem

Switch versions:

sdk use java 21.0.1-tem

Testing Your Installation with a Hello World Program

To confirm your setup, write and run a simple Java program.

Step 1: Create the Program

  1. Create a project directory:
mkdir ~/JavaProjects
   cd ~/JavaProjects
  1. Create a file named HelloWorld.java:
nano HelloWorld.java
  1. Add the following code:
public class HelloWorld {
       public static void main(String[] args) {
           System.out.println("Hello, Java on macOS!");
       }
   }
  1. Save and exit (Ctrl+O, Enter, Ctrl+X).
  2. For a detailed explanation, see Hello World Program.

Step 2: Compile and Run

Compile the program:

javac HelloWorld.java

This creates HelloWorld.class.

Run the program:

java HelloWorld

Output:

Hello, Java on macOS!

Step 3: Troubleshooting

  • “File not found”: Ensure you’re in ~/JavaProjects and HelloWorld.java exists (ls to list files).
  • “Main class not found”: Verify the class name matches (java HelloWorld, not java helloworld).
  • Compilation Errors: Check for typos (e.g., missing semicolon, incorrect class name).

Setting Up a Development Environment

With Java installed, choose a tool for coding:

  • Text Editors: VS Code with the Java Extension Pack, Sublime Text, or TextEdit.
  • IDEs: IntelliJ IDEA Community Edition, Eclipse, or NetBeans offer code completion, debugging, and project management.

To install VS Code: 1. Download from code.visualstudio.com. 2. Drag the .dmg to Applications. 3. Open VS Code, go to Extensions (Cmd+Shift+X), and install the Java Extension Pack. 4. Open ~/JavaProjects in VS Code to start coding.

For IntelliJ IDEA: 1. Download the Community Edition from jetbrains.com. 2. Install and create a new Java project, pointing to your JDK path.

Uninstalling Java (Optional)

To remove Java: 1. Delete the JDK directory:

sudo rm -rf /Library/Java/JavaVirtualMachines/temurin-21.jdk
  1. For Homebrew:
brew uninstall openjdk@21
  1. Remove JAVA_HOME and PATH entries from ~/.zshrc or ~/.bashrc.

FAQ

Do I need both JDK and JRE on macOS?

No, the JDK includes the JRE. Installing the JDK provides all tools for development and running Java programs.

Which Java version should I install on macOS?

Choose an LTS version like Java 21 for stability and support. Java 17 is also suitable for compatibility with older tools.

Why is javac not recognized after installation?

The JDK’s bin folder may not be in your PATH. Add export PATH=$JAVA_HOME/bin:$PATH to ~/.zshrc and run source ~/.zshrc.

Should I use Homebrew or the Adoptium installer?

Use the Adoptium installer for simplicity and a GUI. Use Homebrew for easier version management or if you prefer command-line tools.

How do I manage multiple Java versions on macOS?

Use /usr/libexec/java_home -v <version></version> to switch versions or install SDKMAN! for streamlined management.

Conclusion

Installing Java on macOS is a straightforward process that prepares you to develop and run Java applications. By installing OpenJDK via Adoptium or Homebrew, configuring environment variables, and testing with a Hello World program, you’ve established a robust development environment. Continue your journey by exploring Java concepts like variables, control flow statements, or arrays. With Java set up on your Mac, you’re ready to code, experiment, and build exciting Java projects!