Mise Version Manager

There is no AI here. All content is human-authored and tested for accuracy.

Java with Mise

Mise is multi-language version manager for Mac, replacing Java tools SDKMAN or jenv with a single tool supporting multiple languages. Use Mise to install and switch between Java versions and distributions, configure JAVA_HOME automatically, and manage both Java and build tools from a single .mise.toml file.

Mise is a multi-language version manager that handles Java, Node.js, Python, Ruby, and more from a single command line tool and configuration file. Unlike SDKMAN or jenv, Mise manages installation and version switching for Java and other languages. See Mise on Mac to understand how mise works and why developers switch from language-specific managers. For a broader overview of Java installation options on Mac, see Java on Mac.

Managing Java versions is one step in setting up your Mac for development. See the Mac development setup guide.

Before you get started

You'll need a terminal application to install and use the mise version manager for Java. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

First steps for Java with Mise

If you haven't installed mise yet, see the Install Mise on Mac guide. Verify that mise is working by running mise --version in your terminal. You should also run mise doctor after installation to ensure mise is activated by the ~/.zshrc file and shell hooks load correctly. This allows mise to automatically switch Java versions and set the JAVA_HOME environment variable when you enter directories with a .mise.toml file.

Set a global Java version

To set a default Java version for your entire system, run mise use with the --global flag. This version applies whenever you're in a directory without a .mise.toml file. In this example, we choose the Temurin distribution of Java 25. See my article Java on Mac to learn more about Java distributions and versions.

$ mise use --global java@temurin-25

The global version is stored in ~/.config/mise/config.toml. You can have multiple project-specific versions and still maintain a system-wide default. Mise downloads the precompiled Temurin distribution and installs it to ~/.local/share/mise/installs/java/.

Project configuration files

You'll need a .mise.toml file in your project root to specify the exact Java version and distribution your project requires. This file enables automatic version switching: whenever you navigate into the project directory, mise activates the configured version and sets JAVA_HOME. Commit this file to version control so your team uses identical Java versions. See Mise Configuration on Mac for other settings including environment variables, automated tasks, and advanced setup.

Existing projects with Mise for Java

If you have an existing Java project, you can use mise edit to create a .mise.toml configuration file. Instead of writing a file by hand, mise edit launches a terminal-based interactive editor (a TUI) that knows the structure of mise configuration and can search the tool registry for you. If your project already has a .sdkmanrc file, mise reads it automatically.

New projects with Mise for Java

If you are starting a new Java project, open your terminal application and navigate to your project directory. Run the command to install Java with the Temurin distribution.

$ mise use java@temurin-25

If you haven't installed a global Java version yet, Mise downloads the latest precompiled binary from the Temurin distribution and installs it to ~/.local/share/mise/installs/java/. The command creates a .mise.toml file in your current directory with the installed version.

The configuration file is simple:

[tools]
java = "temurin-25"

Verify the installation by checking the Java version.

$ java --version
$ javac --version

Both commands should display version information. The javac command verifies the Java compiler is available for development.

Install a specific Java version

If your project requires a particular Java version, specify it using the Temurin prefix and version number.

$ mise use java@temurin-17

This installs Java 17, an older version that is common in legacy projects. To pin an exact version, use the --pin flag.

$ mise use --pin [email protected]

The --pin flag records the complete version string in .mise.toml, ensuring consistent behavior across your team.

A choice of Java distributions

Java comes from multiple vendors, each offering their own distribution. Temurin is the recommended choice for most developers because it is free, open source, and receives long-term support. See my article the Java JDK to learn more about Java distributions and versions.

Eclipse Temurin is a free and open source implementation of the Java Platform, Standard Edition. It is backed by the Eclipse Foundation, IBM, and Red Hat. Temurin passes Oracle's compatibility tests (TCK certification), ensuring compatibility with any Java application. See OpenJDK on Mac for background on the open-source Java ecosystem that Temurin and other distributions build on.

Other distributions serve specialized purposes. Java can also be installed via Homebrew Cask as an alternative to mise for simple single-version setups. Zulu from Azul provides commercial support options. Amazon Corretto is optimized for AWS environments. GraalVM offers ahead-of-time compilation for smaller footprint and faster startup.

For most projects, Temurin is the ideal choice. It is used widely in enterprise environments, has no licensing concerns, and receives four years of long-term support per major version.

Use alternative Java distributions

If your project requires a different distribution, specify it in the version string.

$ mise use java@zulu-21
$ mise use java@corretto-21
$ mise use java@graalvm-22

Each distribution has its own version numbers and features. Zulu offers commercial support, Corretto integrates with AWS, and GraalVM provides advanced optimization capabilities.

Discover available Java versions

Before installing, you can browse all available Java distributions and versions using mise ls-remote java. This command shows every version available for installation.

$ mise ls-remote java

The output shows available distributions with their versions. You can filter by distribution to see specific options.

$ mise ls-remote java@temurin

This displays every available Temurin version, helping you identify stable and recent releases.

Understand Java LTS versions

Java releases new versions every six months, but only some receive long-term support (LTS). LTS versions get security updates for years. Non-LTS versions (such as 22, 23, 24) receive updates for only six months, so avoid them for production.

JDK 25, released September 2025, is the current LTS version and the recommended choice for new projects. See Java 25 on Mac for details on what is new in JDK 25. It will receive support until at least 2033. JDK 21, released September 2023, is the previous LTS version and remains a solid choice if your frameworks or dependencies do not yet support 25. See Java 25 vs Java 21 to compare the two LTS versions. JDK 17 and JDK 11 are older LTS versions still in use by many legacy projects. JDK 8 remains in extended support but should only be used when a specific project requires it.

For most developers, use the latest LTS version (currently JDK 25) unless your team or project requires an older one.

Handle .sdkmanrc files

If you're migrating from the Java version manager SDKMAN or have projects using .sdkmanrc files, mise reads them automatically. No conversion is necessary.

Mise can read SDKMAN configuration files that specify Java and build tool versions.

java=21.0.2-tem
maven=3.9.1
gradle=8.5

When mise encounters a .sdkmanrc file, it installs the specified versions. The vendor abbreviations map to distributions: tem becomes Temurin, zul becomes Zulu, cor becomes Corretto.

Note that some SDKMAN vendors (Bisheng, Liberica NIK) aren't supported by mise. If your .sdkmanrc specifies unsupported vendors, you'll need to adjust the configuration or install those tools separately.

Mise will read a lagacy .sdkmanrc file, but you might want to use a .mise.toml file because it gives you more options, as described in Mise Configuration.

Migrate from SDKMAN to mise

If you currently use SDKMAN, switching to mise takes just a few steps. Your existing Java workflow is preserved while simplifying your tool setup.

You can install Java globally with mise use -g java@temurin-25 (using the -g flag) or install Java versions with mise in each of your projects:

$ mise use java@temurin-25

Comment out the SDKMAN initialization lines in your shell configuration file. If you use zsh, open ~/.zshrc and find lines that source SDKMAN (usually near the end). Comment them out or delete them, then save the file.

After restarting your terminal, mise handles Java version management instead of SDKMAN. Your existing .sdkmanrc files work automatically with mise.

Convert build tool versions

If your .sdkmanrc specifies Maven and Gradle versions, add those to your mise configuration.

[tools]
java = "temurin-25"
maven = "3.9"
gradle = "8.5"

This single file replaces your .sdkmanrc configuration, making project setup more straightforward.

Migrate from jenv to mise

If you currently use the Java version manager jenv, switching to mise is simple because mise installs Java distributions while jenv only switches between existing JDKs.

You can install Java globally with mise use -g java@temurin-25 (using the -g flag) or install Java versions with mise in each of your projects:

$ mise use java@temurin-25

Comment out the jenv initialization lines in your shell configuration file. If you use zsh, open ~/.zshrc and find lines that source jenv. Comment them out or delete them, then save the file.

After restarting your terminal, mise manages your Java versions and sets JAVA_HOME automatically. You don't need to maintain jenv's JDK installation structure.

Switch between Java versions per project

One of mise's most powerful features is automatic version switching. When you navigate into a project directory with a .mise.toml file, mise automatically switches to that project's Java version.

Create two project directories with different Java versions to see this in action. In the first project, create a .mise.toml specifying Temurin Java 17.

$ cd legacy-service/
$ mise use java@temurin-17
$ java --version
openjdk version "17.x.x"

Create a second project directory and install Java 25.

$ cd ../modern-service/
$ mise use java@temurin-25
$ java --version
openjdk version "25.x.x"

Now navigate back to the legacy service. Mise automatically switches the version.

$ cd ../legacy-service/
$ java --version
openjdk version "17.x.x"

This automatic switching happens whenever you enter a directory containing version specifications, making it impossible to accidentally use the wrong Java version.

Follow best practices for Java versions

When managing Java versions across your projects, follow these practices to prevent conflicts and maintain consistency.

Always specify Java versions in .mise.toml for projects you plan to share with others or maintain long-term. This ensures new team members and future versions of yourself use identical configurations.

Use exact version pinning for production projects. The --pin flag creates reproducible builds across environments.

$ mise use --pin [email protected]

For monorepos with multiple services, each subdirectory can have its own .mise.toml. Mise automatically switches versions when entering different subdirectories.

Keep your global Java version at a current LTS release that matches your most common work. This provides a sensible fallback when you're outside project directories.

Use different Java versions for different tasks

Advanced workflows sometimes require different Java versions for different purposes. Mise supports executing specific commands with non-default versions.

Use mise exec to run a single command with a specific Java version without changing your default.

$ mise exec java@temurin-17 -- java --version
openjdk version "17.x.x"

This approach is useful for testing compatibility with older versions or running tools that require specific Java versions without permanently switching.

Verify your setup

After configuring mise for Java, verify the setup is complete and working correctly.

Check that mise is recognizing your .mise.toml configuration.

$ mise current java

This displays the current Java version mise is using. It should match your .mise.toml specification.

Understand JAVA_HOME

JAVA_HOME is an environment variable pointing to your Java installation directory. Build tools like Maven and Gradle use JAVA_HOME to locate the Java compiler and runtime.

Mise automatically sets JAVA_HOME when you switch Java versions. No manual configuration is needed in typical scenarios.

When you run java --version, it uses the JAVA_HOME that mise set. When you change directories to a project with a different Java version, mise updates JAVA_HOME automatically.

Verify JAVA_HOME is set correctly with this command.

$ echo $JAVA_HOME

The output should display the path to your current Java installation. If running from a project directory, this path points to the mise installation for that project's Java version.

Configure JAVA_HOME manually (advanced)

Some legacy macOS applications expect Java to be installed in /Library/Java/JavaVirtualMachines/. While modern tools recognize JAVA_HOME, older applications might need symlinks.

For advanced setups, create a symlink from mise's installation to the system location.

$ sudo mkdir -p /Library/Java/JavaVirtualMachines/
$ sudo ln -s ~/.local/share/mise/installs/java/temurin-25/Contents \
  /Library/Java/JavaVirtualMachines/temurin-25.jdk/Contents

This approach allows older applications to discover Java through the traditional system location while mise continues managing versions.

Use Maven with Mise

Maven is the primary build tool for Java projects. Mise manages the Java version that Maven runs with, while Maven itself manages dependencies and compilation.

After mise switches to your project's Java version, Maven automatically uses that version.

$ mvn clean package

Maven runs using the Java version and distribution specified in your .mise.toml file. No additional configuration is needed.

Manage Maven versions

You can also manage Maven versions with mise alongside Java versions.

[tools]
java = "temurin-25"
maven = "3.9"

This ensures both Java and Maven are available at the correct versions for your project.

Use Gradle with Mise

Gradle is another popular Java build tool. Mise manages the Java version while Gradle handles dependency resolution and compilation.

By default, Gradle uses the JAVA_HOME environment variable that mise sets. After entering your project directory, Gradle automatically uses the correct Java version.

$ gradle build

Gradle runs using the Java version and distribution specified in your .mise.toml file.

Configure Gradle for specific Java versions

If you need explicit control, configure Gradle to use a specific Java installation. Add this to gradle.properties in your project.

org.gradle.java.home=/Users/username/.local/share/mise/installs/java/temurin-25

Replace the path with your specific Java version. This approach provides explicit control if your build system requires it.

Troubleshoot Java issues

If version switching isn't working, verify that mise's shell hooks are loaded. Restart your terminal completely (close all tabs) to ensure the latest shell configuration is loaded. Run mise doctor for diagnostics to ensure mise is activated by the ~/.zshrc file.

Check that .mise.toml exists in your project directory and contains valid configuration.

$ cat .mise.toml

The file should have a [tools] section with java = "distribution-version". If the file is missing, run mise use java@temurin-25 to create it.

If your system cannot locate Java, see Fix unable to locate Java on Mac. If JAVA_HOME isn't setting correctly, verify the Java version is installed.

$ mise ls

The output should list your installed Java versions. If the expected version isn't listed, install it with mise use.

If Maven or Gradle can't find Java, explicitly set JAVA_HOME in your shell. See the article Set JAVA_HOME on Mac.

$ export JAVA_HOME=$HOME/.local/share/mise/installs/java/temurin-25
$ mvn clean package

This forces your build tool to use the mise-installed Java version.

Set up IDE integration

Popular Java IDEs automatically detect mise-installed Java distributions. IntelliJ IDEA recognizes mise installations and allows you to select them as the project SDK.

If your IDE doesn't automatically detect Java, you can manually configure it. In IntelliJ IDEA or Eclipse, point to the mise installation directory.

The path is: ~/.local/share/mise/installs/java/distribution-version/Contents/Home

Replace "distribution-version" with your specific distribution and version. This allows IDEs to use mise-managed Java for compilation, debugging, and other development features.

Use Java across your development stack

Mise's true power emerges when managing multiple languages. Many modern applications use Java for backend services alongside Node.js or Python for other components.

Create a .mise.toml file specifying all your project's language requirements.

[tools]
java = "temurin-25"
node = "24"
maven = "3.9"

When you enter this project directory, mise activates Java 25, Node.js 24, and Maven 3.9 simultaneously. No tool switching or manual environment configuration is needed.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.