asdf-java Plugin

On Apple Silicon Macs, asdf list all java only shows JVMs compatible with your current architecture.

• Native ARM64: The default mode for Apple Silicon.
• Rosetta (x86_64): To install and use x86_64 versions, you must run your terminal under Rosetta translation. You can switch your current shell session to x86_64 using:

arch -x86_64 /bin/zsh

# Check current architecture
arch

# Switch to x86_64 for Rosetta compatibility
arch -x86_64 /bin/zsh

To ensure JAVA_HOME is automatically set to the version currently managed by asdf, add the appropriate initialization script to your shell configuration file.

To use this plugin, you must first have asdf installed. Add the asdf-java plugin using the following command:

Requirements

• bash v5.0
• curl
• unzip
• sha256sum (Linux only)

asdf plugin add java https://github.com/halcyon/asdf-java.git

You can discover available JDKs and install specific versions using the asdf CLI.

List all available JDKs

Use asdf list all java to see the full list of candidate versions.

Install a specific version

Install a candidate by specifying its exact name:

asdf install java <version-name>

asdf list all java
asdf install java adoptopenjdk-11.0.16+8

Once a version is installed, you can set it globally, for the current shell, or for a specific directory.

Set version for current shell (and parent)

Use the -u flag to set the version for the current shell session: asdf set -u java <version>

Set version for local directory

To pin a version to the current directory (writing to .tool-versions), use: asdf set java <version>

Use the latest major version

You can use the latest: prefix to resolve to the most recent patch of a major version. For example, latest:adoptopenjdk-11 will resolve to the newest available adoptopenjdk-11.x.x version.

asdf set -u java adoptopenjdk-11.0.16+8
asdf set java adoptopenjdk-11.0.16+8
asdf install java latest:adoptopenjdk-11

Some macOS applications rely on the /usr/libexec/java_home utility to locate the JDK. You can enable integration with this utility by setting java_macos_integration_enable to yes in your .asdfrc file.

Note: This only works for Java distributions that explicitly support this integration (e.g., it may not work for liberica).

java_macos_integration_enable=yes

By default, asdf-java only installs General Availability (GA) stable releases. To use Early Access builds, you must configure the java_release_type setting in your .asdfrc file.

Supported values for java_release_type:

• ga: Only stable releases (default)
• ea: Only Early Access/unstable builds
• all: Both GA and EA builds

Enabling EA builds

1. Add java_release_type=all (or ea) to your .asdfrc file.
2. Clear the asdf-java cache to force a refresh of available versions:

export ASDF_JAVA_CACHE_DIR="${TMPDIR:-/tmp}/asdf-java.cache/"
rm -rf "$ASDF_JAVA_CACHE_DIR"

# Example: enabling all builds
echo "java_release_type=all" >> ~/.asdfrc

# Clear cache to refresh version list
export ASDF_JAVA_CACHE_DIR="${TMPDIR:-/tmp}/asdf-java.cache/"
rm -rf "$ASDF_JAVA_CACHE_DIR"

On macOS, you can integrate installed Java versions with /usr/libexec/java_home. This allows macOS system tools to recognize the asdf-managed Java versions.

To enable this, set java_macos_integration_enable = yes in your .asdfrc.

Integration Locations:

• User Home (Default): If java_macos_integration_in_home = yes is set, files are placed in $HOME/Library/Java/JavaVirtualMachines/. This does not require root permissions.
• System Directory: If java_macos_integration_in_home is not set to yes, the plugin attempts to install to /Library/Java/JavaVirtualMachines/, which requires sudo (root) permissions.

You can control which types of Java releases are fetched by setting the java_release_type configuration key in your .asdfrc file. This affects the results of list all and the available versions for install.

Supported values:

• ga: General Availability builds (default)
• ea: Early Access builds
• all: All available builds

To remove a Java version installed via this plugin, use the uninstall command. This will remove the files from your asdf installation path and, if configured, attempt to remove macOS /usr/libexec/java_home integrations.

asdf uninstall java <version>

To see all available Java versions that can be installed via this plugin, use the list all command. The plugin fetches release data based on your operating system and architecture to provide an accurate list of compatible versions.

asdf list all java

To install a specific Java version, use the install command followed by the version string. The plugin will automatically detect your OS and architecture, download the appropriate package, verify its checksum, and extract it to your asdf installation directory.

Requirements:

• unzip must be installed on your system if the package is a .zip file.
• An active internet connection to download release data and packages.

asdf install java <version>