How to Change Java JDK on macOS: 5 Beginner Mistakes and Their Solutions

How to Change Java (JDK) Version on macOS Without a Headache: A Guide for Those Tired of Errors

Have you ever tried to run an old Java project, only to have it crash with an error? Or, on the contrary, does your new IDE require JDK 17 while you have JDK 8 installed? If you work on macOS, you've likely encountered that switching Java versions feels like a quest. It seems the java -version command has a mind of its own and doesn't obey your wishes.

On Stack Overflow, the question "How to set or change the default Java (JDK) version on macOS?" has gathered thousands of views and hundreds of comments. People get confused with paths, forget about JAVA_HOME, and accidentally break their system. Let's figure it out once and for all: how to manage JDK on a Mac, what mistakes await beginners, and how to avoid them.

This article is not dry documentation. We'll go from complete chaos to a clear understanding. Let's go!

Why Does macOS Work So "Strangely" with Java?

The first thing to understand: macOS is a Unix system, and it doesn't like it when you manually shove files into folders where they don't belong. Apple installs JDK by default in /Library/Java/JavaVirtualMachines/, and system utilities like /usr/bin/java are just wrappers that look at your JAVA_HOME.

The most common mistake is trying to rename or delete the JDK folder. Don't do that! Instead, you need to learn how to manage symbolic links and environment variables.

Step 1: Find Out Which JDKs You Already Have Installed

Before changing anything, let's see what you have. Open Terminal and run:

/usr/libexec/java_home -V

You'll see something like:

Matching Java Virtual Machines (3):\n    17.0.6 (x86_64) "Oracle Corporation" - "Java SE 17.0.6" /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home\n    11.0.18 (x86_64) "Oracle Corporation" - "Java SE 11.0.18" /Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home\n    1.8.0_361 (x86_64) "Oracle Corporation" - "Java SE 8" /Library/Java/JavaVirtualMachines/jdk1.8.0_361.jdk/Contents/Home

This is the complete list of JDKs the system knows about. If you installed a JDK via Homebrew or manually, but it doesn't show up, it means it's in the wrong folder or doesn't have the correct structure.

Mistake #1: Thinking export JAVA_HOME is Permanent

Beginners often type in the terminal:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home\njava -version  # shows 17

And they're happy. But as soon as you close the terminal and open a new one, everything reverts to the old version. Why? Because export only works in the current session.

Solution: Add this line to your shell configuration file. If you use zsh (the default shell on macOS since Catalina and later), edit the ~/.zshrc file:

echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 17)' >> ~/.zshrc\nsource ~/.zshrc

If you have bash (older versions of macOS), the file is called ~/.bash_profile.

Mistake #2: Confusion Between java and javac

You changed JAVA_HOME, the java -version command shows the desired version, but javac -version stubbornly shows the old one. Sound familiar?

This happens because java and javac are different executable files. Sometimes they can be from different JDKs. Check where they are located:

which java   # /usr/bin/java\nwhich javac  # /usr/bin/javac

If the paths are the same, the problem is that /usr/bin/java is a symbolic link that might point to the old version. Update it using the java_home utility: