Skip to main content

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

Windows is installed via pip. Run jdk from Git Bash or another terminal; PowerShell and cmd do not have shell integration for auto environment switching yet.

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 upgrade <DISTRO>

Upgrade an installed distribution to the latest patch version. Uses the cached catalog; run jdk outdated first if it may be stale.

jdk upgrade zulu-21

jdk outdated

List installed distributions that have newer versions available. Fetches the latest catalog before comparing, so results are current even within the cache TTL.

jdk outdated

jdk update

Sync the local JVM database with the latest release data, bypassing the cache.

jdk update

jdk vendors

List all available JDK vendors.

jdk vendors

jdk editions

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

jdk editions

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

Metadata

Release files for jdkman 0.6.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jdkman 0.6.8
File Size Uploaded Provenance Actions
jdkman-0.6.8.tar.gz 28.7 kB Without provenance Details for jdkman-0.6.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jdkman 0.6.8
File Interpreter ABI Platform Actions
jdkman-0.6.8-py3-none-any.whl Python 3 none any Details for jdkman-0.6.8-py3-none-any.whl

Total release size: 68.8 kB

Release files / jdkman-0.6.8.tar.gz

Download URL jdkman-0.6.8.tar.gz
Size 28.7 kB
Tags Source
SHA-256 checksum
How to use checksums
aed84a07e39d3f5c47b19c1d99b33c7992af667aed970360d1dbc1d8f06afcd5
BLAKE2b-256 checksum
How to use checksums
026a32e300268fc4230e615892b1c80aeaafa3154ff4091e3e7f3aa1a66fcd48
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / jdkman-0.6.8-py3-none-any.whl

Download URL jdkman-0.6.8-py3-none-any.whl
Size 40.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4a8d99c847012a1f6ce30a9e21b0b70d230335302a085c5222d42425acc3aa1e
BLAKE2b-256 checksum
How to use checksums
98d4df17f20c15687aab05e5e8fbcc84119f938121112b4c9c4537bf61d28002
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for jdkman 0.6.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.8 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page