jdkman 0.3.9

A command-line tool for installing and managing OpenJDK distributions.

jdkman

A command-line tool for installing and managing JVM distributions, and switching Java environments.

---

Why jdkman?

JDK Management — Simple by Design

How often do you actually need to pick between 21.0.3 and 21.0.5? Probably never. "The latest Zulu 21" is almost always good enough.

jdkman manages JDKs at exactly that level — no more, no less.

• jdk install zulu-21 — just pick a vendor and a major version
• jdk upgrade zulu-21 — updates to the latest patch automatically
• One installation per vendor + major version, always

No scrolling through minor version lists. No patch versions piling up.

On macOS, JDKs are installed under ~/Library/Java/JavaVirtualMachines/ — the standard path where Gradle, IntelliJ, and most other tools automatically look for JDKs. No extra configuration needed.

Per-Project Java Environment Switching — Like jenv, But Integrated

Beyond managing installations, jdkman also handles per-project Java environment switching, just like jenv.

• Set a Java version per directory with jdk use zulu-21
• A .java-version file is created in the current directory — fully compatible with jenv
• JAVA_HOME is automatically switched as you cd between projects
• Falls back to a global setting when no local .java-version is found
• Create short aliases like jdk alias 21 zulu-21 for convenience

Since jdkman uses the same .java-version file format as jenv, you can adopt jdkman in a team that already uses jenv — both tools will pick up the same file.

---

Installation

Homebrew (recommended):

brew install xunyss/tap/jdkman

pip:

pip install jdkman

Quick Start

# Browse available JDK distributions
jdk remote

# Install a distribution
jdk install zulu-21

# List installed distributions
jdk list

# Check for outdated installations
jdk outdated

---

Shell Integration (Auto Environment Switching)

To enable automatic JAVA_HOME switching when you change directories, add the following to your shell configuration file.

zsh (~/.zshrc):

eval "$(jdk activate zsh)"

bash (~/.bashrc or ~/.bash_profile):

eval "$(jdk activate bash)"

fish (~/.config/fish/config.fish):

jdk activate fish | source

Once activated, jdkman reads the .java-version file in your current directory (or any parent directory) and sets JAVA_HOME automatically. If no local file is found, it falls back to the global setting configured with jdk use --global.

---

Commands

Management

jdk remote [DISTRO]

Browse JDK distributions available for download.

By default, shows only stable JDK builds. Use flags to include additional build types.

jdk remote                    # List all stable JDK builds
jdk remote zulu               # Filter by vendor prefix
jdk remote --version 21       # Filter by major version
jdk remote --all              # Include JRE and feature builds
jdk remote --with-jre         # Include JRE builds
jdk remote --with-feat        # Include feature builds (e.g. JavaFX, CRaC)
jdk remote --all zulu         # Combined: all build types, zulu only

Options:

Option	Short	Description
--version	-v	Filter by major version number
--all	-a	Include all build types
--with-jre	-R	Include JRE builds
--with-feat	-F	Include feature builds

---

jdk install <DISTRO>

Download and install a JDK distribution.

jdk install zulu-21
jdk install temurin-17
jdk install zulu-jre-21          # JRE variant
jdk install zulu-javafx-21       # With JavaFX
jdk install zulu-crac-21         # With CRaC
jdk install zulu-javafx-jre-21   # JRE + JavaFX

The DISTRO name follows this pattern:

{vendor}[-{feature}][-jre]-{major_version}

Use jdk remote to find the exact distribution name.

---

jdk list

Show all installed JDK distributions managed by jdkman.

jdk list
jdk ls      # alias

---

jdk uninstall <DISTRO>

Remove an installed JDK distribution.

jdk uninstall zulu-21
jdk rm zulu-21        # alias

---

jdk upgrade <DISTRO>

Upgrade an installed distribution to the latest patch version.

jdk upgrade zulu-21
jdk upd zulu-21       # alias

---

jdk outdated

List installed distributions that have newer versions available.

jdk outdated

---

jdk vendors

List all available JDK vendors.

jdk vendors
jdk vd        # alias

---

jdk editions

List all available JDK editions (vendor + feature combinations).

jdk editions
jdk ed         # alias

---

Environment

jdk use <DISTRO|ALIAS>

Set the Java environment for the current directory. Creates a .java-version file in the current directory.

jdk use zulu-21           # Set local (current directory)
jdk use 21                # Use an alias
jdk use zulu-21 --global  # Set global fallback (~/.config/jdkman/.java-version)

The .java-version file format is compatible with jenv.

---

jdk unuse

Clear the Java environment for the current directory or globally.

jdk unuse           # Remove local .java-version
jdk unuse --global  # Clear global setting

---

jdk env

Show the currently active Java environment and where it comes from.

jdk env

Displays the active distribution, version, scope (local/global), and the source .java-version file path.

---

jdk alias <ALIAS> <DISTRO>

Create a short alias for an installed distribution.

jdk alias 21 zulu-21       # Use "21" instead of "zulu-21"
jdk alias lts temurin-21

---

jdk unalias <ALIAS>

Remove an alias.

jdk unalias 21

---

jdk aliases

List all defined aliases and their status.

jdk aliases

---

jdk activate <SHELL>

Print the shell integration script that enables auto-switching.

eval "$(jdk activate zsh)"   # Add to ~/.zshrc
eval "$(jdk activate bash)"  # Add to ~/.bashrc
jdk activate fish | source   # Add to ~/.config/fish/config.fish

---

jdk deactivate <SHELL>

Remove the shell integration (auto-switching).

eval "$(jdk deactivate zsh)"
eval "$(jdk deactivate bash)"
jdk deactivate fish | source

---

Tools

jdk cleanup

Remove cached data (downloaded archives and catalog cache).

jdk cleanup
jdk clean     # alias
jdk clear     # alias

---

jdk home (macOS only)

Show Java home paths for JVMs registered with the system.

jdk home           # List registered Java installations
jdk home --json    # Show detailed info in JSON format

---

jdk mise [DISTRO]

List or register JVM distributions as mise java tools.

jdk mise             # List current mise java tools
jdk mise zulu-21     # Register a distribution as a mise java tool

---

About

jdk version

Show the jdkman version.

jdk version
jdk --version
jdk -v

---

How Per-Project Switching Works

1. Add eval "$(jdk activate zsh)" (or bash, or jdk activate fish | source for fish) to your shell config.
2. Run jdk use zulu-21 in a project directory — this creates a .java-version file.
3. Every time you cd into that directory (or any subdirectory), jdkman reads the nearest .java-version upward and sets JAVA_HOME automatically.
4. When you leave the directory, the global setting (or none) takes effect.

~/projects/
├── service-a/
│   └── .java-version   → "zulu-21"   → JAVA_HOME = zulu-21 path
└── legacy-app/
    └── .java-version   → "temurin-17" → JAVA_HOME = temurin-17 path

The .java-version file is a plain text file containing the distribution slug or alias. Because it uses the same format as jenv, teams can mix jdkman and jenv users without conflict.

---

License

MIT