How to set or change the default Java (JDK) version on macOS?

Learn how to set or change the default java (jdk) version on macos? with practical examples, diagrams, and best practices. Covers java, macos development techniques with visual explanations.
Tags:
Categories:

How to Set or Change the Default Java (JDK) Version on macOS

How to Set or Change the Default Java (JDK) Version on macOS

Learn the essential steps to manage multiple Java Development Kit (JDK) installations and configure your default Java version on macOS, ensuring compatibility for your projects.

macOS users often work with various Java projects that might require different JDK versions. While macOS comes with its own Java runtime, developers frequently need specific JDK versions (e.g., Java 8, 11, 17, 21) for their development environments. This article guides you through identifying installed JDKs, installing new ones, and crucially, setting or changing the default Java version for your system.

Understanding Java Installations on macOS

On macOS, JDKs are typically installed in the /Library/Java/JavaVirtualMachines/ directory. Each JDK version resides in its own subdirectory. Tools like java_home help manage these installations, but direct environment variable manipulation is often required for precise control. It's important to differentiate between the Java Runtime Environment (JRE) and the Java Development Kit (JDK). For development, you'll always need the JDK.

java -version
javac -version

Check the currently active JRE and JDK compiler versions.

/usr/libexec/java_home -V

This command lists all JDKs recognized by java_home.

Installing a New JDK Version

If you don't have the desired JDK version installed, you can download it from various sources. Oracle provides official releases, while OpenJDK distributions like Adoptium (formerly AdoptOpenJDK) offer open-source alternatives. After downloading the .dmg installer, simply run it and follow the on-screen instructions. The installer will place the JDK in the correct /Library/Java/JavaVirtualMachines/ path.

A flowchart diagram showing the process of installing a new JDK on macOS. Steps include: 1. Identify Needed JDK Version (e.g., Java 17), 2. Choose Distribution (Oracle, Adoptium), 3. Download .dmg Installer, 4. Run Installer, 5. Verify Installation with java_home -V. Use blue rounded rectangles for actions, green circles for start/end, and arrows for flow.

Workflow for installing a new JDK on macOS.

Setting the Default Java Version

The most common and effective way to set the default Java version is by configuring your JAVA_HOME environment variable. This variable tells your system and applications which JDK installation to use. You'll typically set this in your shell's configuration file (e.g., ~/.zshrc, ~/.bash_profile, ~/.profile).

1. Step 1

Open your shell configuration file: Use a text editor to open ~/.zshrc (for Zsh, the default shell on modern macOS) or ~/.bash_profile (for Bash). If the file doesn't exist, you can create it.

2. Step 2

Add or modify the JAVA_HOME variable: Append the following lines to your configuration file, replacing jdk-17.0.2.jdk with your desired JDK version's directory name:

3. Step 3

Reload your shell configuration: After saving the file, apply the changes by running source ~/.zshrc (or source ~/.bash_profile) in your terminal.

4. Step 4

Verify the new default Java version: Run java -version and echo $JAVA_HOME to confirm that the changes have taken effect and the correct JDK is now active.

export JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk-17.0.2.jdk/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

This sets JAVA_HOME and adds its bin directory to your PATH.

For developers working with multiple projects requiring different Java versions, tools like jEnv or SDKMAN! can provide more flexible and project-specific Java version management. These tools allow you to switch Java versions on a per-project or per-directory basis without manually editing environment variables.