March 7, 2025

Install OpenJDK 21 Using jenv on macOS: Best Practices & Troubleshooting

Introduction

Java 21 brings exciting new features and improvements, making it a great choice for developers. However, managing multiple Java versions can be a challenge, especially if you work on different projects. This is where jenv comes in—a lightweight Java version manager that helps you seamlessly switch between different JDK versions.

In this guide, we’ll go through the installation of OpenJDK 21 on macOS, how to configure it using jenv, best practices, and troubleshooting common issues.

Why Use jenv?

jenv provides several advantages over manually managing Java versions:

  • Easily switch between Java versions
  • Per-project Java version management
  • Ensures a clean environment by preventing conflicts
  • Works with various JDK distributions like OpenJDK, Amazon Corretto, Azul Zulu, etc.

Step 1: Install OpenJDK 21 on macOS

There are multiple ways to install OpenJDK 21. The most convenient is via Homebrew.

Option 1: Install OpenJDK 21 via Homebrew

If you haven’t installed Homebrew yet, install it first:

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

Now, install OpenJDK 21:

brew install openjdk@21

After installation, Homebrew will provide instructions to add OpenJDK 21 to your system PATH. Run the following:

echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc  # Reload the shell configuration

Option 2: Manual Installation

If you prefer downloading OpenJDK 21 manually:

  1. Download OpenJDK 21 from Adoptium or OpenJDK.
  2. Extract the file and move it to /Library/Java/JavaVirtualMachines/: 
    sudo mv jdk-21.jdk /Library/Java/JavaVirtualMachines/
  3. Set JAVA_HOME manually (explained in Step 3).

Step 2: Install and Configure jenv

Installing jenv

If you haven’t installed jenv, use Homebrew:

brew install jenv

Next, add jenv to your shell profile:

echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc
source ~/.zshrc

For bash users, replace ~/.zshrc with ~/.bash_profile.

Verify the installation:

jenv --version

Step 3: Add OpenJDK 21 to jenv

Find the installed Java version:

/usr/libexec/java_home -V

This will display all installed Java versions. Locate OpenJDK 21’s path and add it to jenv:

jenv add /opt/homebrew/opt/openjdk@21

Set Default Java Version

To set Java 21 as the global version:

jenv global 21

For project-specific Java versions:

cd /path/to/your/project
jenv local 21

Confirm the version:

java -version

Expected output:

openjdk version "21" 2023-09-19
OpenJDK Runtime Environment (build 21+35)
OpenJDK 64-Bit Server VM (build 21+35, mixed mode)

Step 4: Set JAVA_HOME (If Needed)

Some applications require JAVA_HOME to be set explicitly. Run:

echo 'export JAVA_HOME=$(jenv prefix 21)' >> ~/.zshrc
source ~/.zshrc

Confirm:

echo $JAVA_HOME

Troubleshooting Common Issues

1. java -version Still Shows an Old Version

  • Run: 
    jenv rehash
jenv global 21
  • If the issue persists, manually set JAVA_HOME: 
    export JAVA_HOME=$(/usr/libexec/java_home -v 21)

2. jenv: command not found

  • Ensure jenv is installed and initialized properly: 
    source ~/.zshrc
jenv --version

3. jenv versions Doesn’t Show Java 21

  • Check if OpenJDK 21 was added to jenv: 
    jenv add /opt/homebrew/opt/openjdk@21
  • If it still doesn’t appear, run: 
    jenv rehash

4. command not found: java

  • Ensure Java is correctly linked: 
    sudo ln -sfn /opt/homebrew/opt/openjdk@21/bin/java /usr/local/bin/java
  • If using jenv, make sure it’s managing Java: 
    jenv global 21

Upcoming Changes in Java & jenv

Java continues to evolve, with new features in Java 21, such as:

  • Virtual Threads (Project Loom) for better concurrency handling.
  • Record Patterns and Pattern Matching enhancements.
  • Sequenced Collections API for improved collection handling.
  • New Garbage Collection Improvements for better performance.

jenv remains a powerful tool for managing these updates efficiently.

Conclusion

By installing OpenJDK 21 and managing it with jenv, you ensure a seamless Java development experience. This approach helps prevent conflicts, enables per-project Java version management, and keeps your environment clean.

Final Checklist:

✅ Installed OpenJDK 21 via Homebrew or manually.
✅ Installed and configured jenv.
✅ Added Java 21 to jenv and set it as the default.
✅ Set JAVA_HOME (if needed).
✅ Verified installation and fixed common issues.

Following these best practices ensures a smooth Java development workflow on macOS. 🚀 Happy coding!

Further Reading:

Posted by
Labels: