Automatically Switch JDK Versions per Project with jenv

What is jenv

jenv is a lightweight Java version manager comparable to nvm for Node.js. It manages already‑installed JDKs, provides global version selection, automatic project‑level switching, temporary shell‑level switching, and can synchronize JAVA_HOME via the export plugin. jenv does not install JDKs itself.

Installation

Install jenv

brew install jenv

Shell configuration

Add the following lines to ~/.zshrc and reload the shell:

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

Run source ~/.zshrc or restart the terminal.

Basic usage

1. Install JDKs (Homebrew)

brew tap bell-sw/liberica
brew install --cask liberica-jdk8
brew install --cask liberica-jdk17
brew install --cask liberica-jdk21

2. Locate JDK paths

/usr/libexec/java_home -V

Typical output lists the full paths of the installed JDKs, e.g.:

Matching Java Virtual Machines (3):
  21.0.10+10-LTS (arm64) "BellSoft" - "BellSoft Liberica JDK 21.0.10+10" /Library/Java/JavaVirtualMachines/liberica-jdk-21.jdk/Contents/Home
  17.0.18+10-LTS (arm64) "BellSoft" - "BellSoft Liberica JDK 17.0.18+10" /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home
  1.8.0_482-b10 (arm64) "BellSoft" - "Liberica JDK 1.8.0_482-b10" /Library/Java/JavaVirtualMachines/liberica-jdk-8.jdk/Contents/Home

3. Add JDKs to jenv

jenv add /Library/Java/JavaVirtualMachines/liberica-jdk-8.jdk/Contents/Home
jenv add /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home
jenv add /Library/Java/JavaVirtualMachines/liberica-jdk-21.jdk/Contents/Home

jenv creates several aliases for each JDK (e.g. 21, 21.0, 21.0.10, openjdk64-21.0.10). Unwanted aliases can be removed with jenv remove <alias>.

Note: The major‑version alias for JDK 8 is 1.8 , not 8 . The version string shown by jenv versions is 1.8.0.482 , not 1.8.0_482 .

4. List managed versions

jenv versions

Sample output:

system
  1.8
  17
* 21 (set by /Users/username/.jenv/version)

5. Switch Java versions

Global switch (affects new terminals): jenv global 21 Project‑level switch (automatic when entering a directory):

cd ~/my-project
jenv local 17

This creates a .java-version file in the directory; leaving the directory restores the global version.

Shell‑level switch (current terminal session only):

jenv shell 17

6. Enable the export plugin

By default jenv does not modify JAVA_HOME. Enable automatic synchronization with: jenv enable-plugin export After enabling, JAVA_HOME follows the selected JDK, preventing Maven or Gradle from using the wrong version.

Practical example

# Set global default to JDK 17
jenv global 17

# Configure old project to use JDK 8
cd ~/project-a
jenv local 1.8
java -version   # → openjdk version "1.8.0_482"

# Verify new project uses JDK 17
cd ~/project-b
java -version   # → openjdk version "17.0.18"

Entering each project directory automatically switches the Java version, and leaving restores the global JDK 17.

Common commands cheat sheet

jenv versions

– list all managed versions jenv add <path> – add a JDK to jenv jenv remove <alias> – delete a specific alias jenv global <version> – set the global default version jenv local <version> – set version for the current directory (writes .java-version) jenv shell <version> – temporarily switch the version for the current terminal session jenv enable-plugin export – enable automatic JAVA_HOME synchronization jenv which java – show the path of the active java executable

Common issues

jenv does not install JDKs; install them first via Homebrew, then add them with jenv add.

If the shim cache is stuck, remove the stale shim and rehash: rm ~/.jenv/shims/.jenv-shim && jenv rehash Remember to enable the export plugin; otherwise JAVA_HOME will not update and build tools may use the wrong version.

Priority order: shell > local > global.

Conclusion

The core value of jenv is automatic Java version switching when entering a project directory. Combined with Homebrew‑installed JDKs, the workflow eliminates manual JAVA_HOME adjustments.