SDKMAN!
Foundation • https://lgtm-hq.github.io/holy-grailguides/sdkman/
SDKMAN!
SDKMAN! Manage parallel versions of multiple Software Development Kits with SDKMAN!, the SDK manager for JVM-based languages
Foundation Quest #3 Beginner

SDKMAN!

Manage parallel versions of multiple Software Development Kits with SDKMAN!, the SDK manager for JVM-based languages

sdkjavagroovykotlinfoundation
Download as:

What is SDKMAN!?

SDKMAN! is a tool for managing parallel versions of multiple Software Development Kits on most Unix-based systems. It provides a convenient Command Line Interface (CLI) and API for installing, switching, removing, and listing Candidates.

Formerly known as GVM (the Groovy enVironment Manager), it was inspired by the very useful RVM and rbenv tools, used at large by the Ruby community.

Prerequisites

Homebrew foundation ZSH / Oh My ZSH! foundation

Installation

Open a new terminal session:

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

Close your terminal session after installation.

Verify Your Installation

Open a new terminal session:

sdk version

You should see output similar to:

SDKMAN!
script: 5.18.1
native: 0.2.2

Installing SDKs

Install from SDKMAN

Install the latest version of an SDK:

sdk install <sdk-name>

Install a specific version of an SDK:

sdk install <sdk-name> <version>

When installing multiple versions of an SDK, you may be prompted to set the newly installed SDK as the default version.

Install from Local SDKs (Direct Downloads)

sdk install <sdk-name> <version> </path/to/sdk/file>

The local version name <version> must be a unique name which is not already in the list of available version names.

Uninstalling SDKs

Uninstall a specific version of an SDK:

sdk uninstall <sdk-name> <version>

To remove all versions of an SDK, run this command for each installed version.

Good to Know

Listing Available SDKs

Get a list of all SDKs available through SDKMAN!:

sdk list

This will render a searchable alphabetic list with name, current stable default version, website URL, description, and easy install command for each Candidate. The output is piped to less so standard keyboard shortcuts may be used with q to exit.

Get a list of versions for a specific SDK:

sdk list <sdk-name>

Legend:

  • + - local version
  • * - installed
  • > - currently in use

Version Switching

Switch global versions:

This means that every new project or reference to the specified SDK will use whatever version you set.

sdk default <sdk-name> <version>

Switch versions per project:

In your project directory:

sdk env init

This will create a .sdkmanrc file which will remember the SDK version to be used within this project:

# Enable auto-env through the sdkman_auto_env config
# Add key=value pairs of SDKs to use below
<sdk-name>=<version>

To use the .sdkmanrc file when you open your project:

sdk env

Add sdkman_auto_env=true to the global SDKMAN config at ~/.sdkman/etc/config to automatically switch to the versions specified in .sdkmanrc when you enter a project directory. The .sdkmanrc file itself is only for per-project version mappings (e.g., java=21.0.4-tem).

Check Your Current Default Version

Check the current version of a specific SDK:

sdk current <sdk-name>

Check the current version of all SDKs:

sdk current

Using sdk env

Reset the SDKs to their default version:

sdk env clear

Using a project with an existing .sdkmanrc file may require you to install the SDK:

sdk env install

SDK & SDKMAN! Updates & Upgrades

Updating SDKMAN!:

# option 1
sdk selfupdate

# option 2
sdk selfupdate force

If no new version is available, an appropriate message will be displayed. Automatic daily checks are done for available updates.

Check what needs to be upgraded:

sdk upgrade

Upgrade a specific SDK:

sdk upgrade java

Get Location of SDK

sdk home <sdk-name> <version>
# Output: /home/myuser/.sdkman/candidates/<sdk-name>/<version>

Troubleshooting

”sdk: command not found”

  1. Verify SDKMAN! is installed:

    ls ~/.sdkman

  2. Add initialization to your shell config (~/.zshrc):

    export SDKMAN_DIR="$HOME/.sdkman"
[[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"

  3. Re-source your shell:

    source ~/.zshrc

Version Not Switching

If sdk use or sdk default doesn’t change versions:

  1. Check for conflicting version managers:

    which java  # Should be ~/.sdkman/candidates/java/current/bin/java

  2. Ensure SDKMAN! directories are in PATH before system directories

  3. Check for .sdkmanrc files overriding global settings:

    find . -name ".sdkmanrc" 2>/dev/null

Offline Mode

If you’re offline or have network issues:

# Enable offline mode
sdk offline enable

# List only installed SDKs (marked with *)
sdk list java | grep -E '^\s*\*'

Corrupted Installation

If SDKMAN! behaves unexpectedly:

# Reinstall without losing installed SDKs
rm -rf ~/.sdkman/tmp
sdk selfupdate force

# Or completely reinstall (loses all SDKs)
rm -rf ~/.sdkman
curl -s "https://get.sdkman.io" | bash

Slow Performance

SDKMAN! makes network calls. For faster performance:

# Disable auto-updates in ~/.sdkman/etc/config
sdkman_auto_selfupdate=false
sdkman_auto_update=false

Resources

🔗
SDKMAN! Usage Documentation sdkman.io

Official documentation for all SDKMAN! commands and features
🔗
SDKMAN! Installation sdkman.io

Installation instructions and requirements