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.5

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.5
File Size Uploaded Provenance Actions
jdkman-0.6.5.tar.gz 28.7 kB Without provenance Details for jdkman-0.6.5.tar.gz

Built distribution (wheel)

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

Total release size: 68.8 kB

Release files / jdkman-0.6.5.tar.gz

Download URL jdkman-0.6.5.tar.gz
Size 28.7 kB
Tags Source
SHA-256 checksum
How to use checksums
648e62ca97920d114d468f57ce14c70ee065784022dc9d1d959553798bad7cf3
BLAKE2b-256 checksum
How to use checksums
6b5e8d6c2b0a6bea89d3622bdbe0e0be8c5e9e742bf42e5ddce42574cc5623a8
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.5-py3-none-any.whl

Download URL jdkman-0.6.5-py3-none-any.whl
Size 40.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6e8d83923c14caddc52265551f8b5bb5cb70c834b4466a80352910447b597730
BLAKE2b-256 checksum
How to use checksums
b34eca4d532586cb7a0f61f59259f0288d0ff414efb3fb0b38bcbec4237cc584
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.5

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.5 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