[EN] Goodbye, Versions-Chaos: Ein praktischer Guide zu SDKMAN für Java-Entwickler

Julian | Oct 25, 2025 min read
[EN] Goodbye, Versions-Chaos: Ein praktischer Guide zu SDKMAN für Java-Entwickler

Do you know that too? You are working on Project A, which is still running on Java 11 LTS, while at the same time you are developing a new feature for Project B, which is already based on the current Java 21. And then there is this legacy system that, for some unknown reason, requires Java 8.

The everyday battle begins: manually adjust JAVA_HOME in the .zshrc or .bash_profile, restart the shell and hope that the IDE also notices the change. It’s cumbersome, error-prone and steals valuable time that we would rather invest in coding.

What if there was a tool that could completely do this work for you? A tool that automatically activates the correct Java version as soon as you change to the project directory?

This is exactly where SDKMAN comes into play. This inconspicuous but extremely powerful command line tool revolutionizes the management of software development kits (SDKs) on Unix-based systems. In this article I will not only show you the basics, but above all the game changer for project work: the .sdkmanrc file. Get ready to banish manual JDK changes from your workflow for good.

What is SDKMAN?

Before we dive into practice, let’s briefly clarify what SDKMAN! – the Software Development Kit Manager – is accurate.

At its core, SDKMAN is a command line tool designed for Unix-like operating systems (such as macOS, Linux, WSL on Windows) to simplify the parallel installation and management of different versions of software development kits.

Think of it like a package manager, but specifically for developer tools. The most important advantages at a glance:

  • Multi-SDK support: It not only manages Java versions (from providers like Temurin, Oracle, GraalVM etc.), but also a huge selection of other tools like Gradle, Maven, Groovy, Kotlin, Scala and many more.
  • Easy to install and switch: With simple commands like sdk install java 21-tem or sdk use java 11.0.22-tem, you can install and switch between SDKs without having to adjust manual configuration files.
  • Environment-specific versions: SDKMAN can manage global, shell-specific and, as we’ll see shortly, project-specific versions.
  • New Version Discovery: A simple sdk list java command will show you all available candidates and versions that you can install with one command.

In short: SDKMAN ends the chaos of manual SDK management and gives you back full control of your development environment.

Installation

Now it’s time to get down to business. The installation of SDKMAN is pleasantly uncomplicated and can be completed in just a few moments.

Open your preferred terminal. For Linux, macOS or the Windows Subsystem for Linux (WSL) a single command is sufficient:

curl -s "https://get.sdkman.io" | bash

This command downloads and runs the installation script. Follow the on-screen instructions. At the end of the process, you will be asked to either restart your terminal or run the following command to enable SDKMAN for your current shell session:

source "$HOME/.sdkman/bin/sdkman-init.sh"

The easiest way is often to simply open a new terminal window.

To check if everything worked, enter the following command:

sdk version

If you get a version number back, the installation was successful. Congratulations, you’re ready to go!

A note for Windows users: SDKMAN runs natively on Unix-based systems. The recommended and best way on Windows is to use the Windows Subsystem for Linux (WSL 2). Once you have installed and started a Linux distribution (e.g. Ubuntu) via the Microsoft Store, the steps above are absolutely identical.

Perfect. Now comes the part that will give readers the biggest “aha moment.” We show you how all the manual work is eliminated. Here is the draft for the main part.

The core of the article: Project-specific Java versions with .sdkmanrc

The previous commands were useful, but now comes the feature that turns SDKMAN from a nice tool into an indispensable companion in your everyday developer life.

Imagine entering the directory of a project and your system automatically switches to the correct Java version. No more manual sdk use, no more thinking about the correct version. This is exactly what the .sdkmanrc file allows.

Step 1: Install the correct JDK

First we make sure that the required Java version is installed. Let’s say our project requires Temurin 17. With SDKMAN we can install it easily. First, we list the available candidates to find the right identifier:

# Filtern der Liste nach Temurin (tem) Version 17
sdk list java | grep 17.0 | grep tem

The output shows us different versions. For example, we choose 17.0.12-tem. The installation is done with:

sdk install java 17.0.12-tem

Step 2: Create the .sdkmanrc in the project

Now we go to the root directory of our Java project. There we run a simple command to tell SDKMAN to use the Java version we just installed for this directory:

# Im Projektverzeichnis ausführen
sdk env init

This command creates a new file named .sdkmanrc in the current directory. The content looks something like this:

# Enable auto-env through the sdkman_auto_env config
# Add key=value pairs of SDKs to use below
java=17.0.12-tem

You should definitely check this file into your Git repository. This way the entire team ensures that everyone is automatically using the exact same version of Java, which reduces the famous “but it works for me” problems.

Step 3: Experience the magic

That’s it! If you use SDKMAN in the standard configuration, you still have to confirm that you trust the .sdkmanrc file when you first enter the directory. After that, the magic happens fully automatically.

Exit the directory and re-enter it:

# Verzeichnis verlassen
cd ..

# Projektverzeichnis wieder betreten
cd my-java-project/

# Ausgabe von SDKMAN:
# Using java version 17.0.12-tem in this shell.

Check the active Java version:

java -version

# Erwartete Ausgabe:
# openjdk version "17.0.12" 2024-07-16
# OpenJDK Runtime Environment Temurin-17.0.12+7 (build 17.0.12+7)
# OpenJDK 64-Bit Server VM Temurin-17.0.12+7 (build 17.0.12+7, mixed mode, sharing)

Perfect! SDKMAN automatically activated the correct JDK for you. If you now switch to another project with a different .sdkmanrc file (e.g. for Java 21), the process repeats itself and you are immediately ready to work with the correct environment.

Fantastic objection! This is an extremely important point that further underlines the usefulness of SDKMAN. I’ll install that straight away. I create a new subsection within the main body.

Addition to the main part

More than just Java: Using the ecosystem

The strength of .sdkmanrc is not limited to Java. You can define any SDKs managed by SDKMAN in this file.

Suppose your project requires not only Java 17, but also a very specific Maven version, for example 3.9.6. No problem! Install them first:

sdk install maven 3.9.6

Then adjust your .sdkmanrc file manually or have it regenerated with sdk env init. It then looks like this:

# Enable auto-env through the sdkman_auto_env config
# Add key=value pairs of SDKs to use below
java=17.0.12-tem
maven=3.9.6

Now when you enter the project directory, SDKMAN will switch both Java and Maven versions for you. This ensures a consistent and reproducible build environment across the team.

Bonus: Seamless IDE integration

Modern Java IDEs like IntelliJ IDEA are smart enough to recognize SDKMAN. When you open a project that contains a .sdkmanrc file, the following happens:

  1. The IDE reads the file and recognizes the defined Java version.
  2. It checks whether this JDK is already configured in the IDE.
  3. If not, it proactively suggests that you use this exact SDKMAN-managed JDK for the project.

With a single click, your project is configured correctly in the IDE - without having to manually search in the project settings. This seamless integration completes the workflow and lets you start coding straight away.

Understood. A good conclusion rounds off the article, summarizes the most important things and leaves a lasting impression. Here is my suggestion:

Conclusion

Gone are the days when you had to manually adjust your JAVA_HOME variable or wade through countless JDK installations. As we’ve seen, SDKMAN is much more than just a simple version manager - it’s a powerful tool for automating and standardizing your development environment.

The real turning point is the .sdkmanrc file. It turns a reactive process (manually changing versions) into a proactive, automated workflow.

The most important benefits for you and your team are:

  • Automatic context switching: As soon as you enter a project directory, the correct version of Java, Maven and other tools are available.
  • Reproducible environments: By checking the .sdkmanrc into your Git repository, you ensure that everyone on the team is working with the exact same setup.
  • Seamless IDE integration: Modern IDEs recognize the configuration and set up your project correctly with one click.

If you’re not already using SDKMAN, now is the perfect time to start. Installation only takes a few minutes, but the gains in productivity and reduction in configuration errors are immense. It’s one of those small workflow changes that makes a huge, positive impact.