How To Install SDKMAN on Debian 13

Managing multiple software development kits can quickly become a nightmare for developers working on various projects. Each project might require different versions of Java, Gradle, Maven, or other SDKs, leading to configuration headaches and PATH variable conflicts. SDKMAN solves this problem elegantly by providing a lightweight, command-line tool that manages parallel versions of multiple software development kits on Unix-based systems. This comprehensive guide walks you through installing SDKMAN on Debian 13, configuring it properly, and mastering its essential features to streamline your development workflow.

Whether you’re a Java developer juggling multiple JDK versions, a DevOps engineer managing build tools, or a system administrator setting up development environments, SDKMAN offers a unified solution. Built with Rust and bash, it requires minimal dependencies while delivering maximum flexibility. By the end of this tutorial, you’ll have a fully functional SDKMAN installation and understand how to leverage its powerful features.

What is SDKMAN?

SDKMAN, short for Software Development Kit Manager, is an open-source tool designed specifically for managing parallel versions of multiple SDKs on most Unix-based systems. It supports a wide range of programming languages, frameworks, and build tools including Java, Kotlin, Scala, Groovy, Gradle, Maven, Spring Boot, and dozens more.

The tool eliminates the tedious process of manually downloading SDK archives, extracting them, configuring environment variables, and updating PATH settings. Instead, SDKMAN handles everything through simple command-line instructions. It’s cross-platform compatible, working seamlessly on Linux distributions like Debian, Ubuntu, and Fedora, as well as macOS and Windows Subsystem for Linux (WSL).

What sets SDKMAN apart is its lightweight nature. Unlike heavy-handed package managers, it requires only curl, zip, and unzip utilities. This minimal footprint means faster installation, reduced system overhead, and fewer potential conflicts with existing software.

For Debian 13 users, SDKMAN provides particular advantages. Debian’s stable repository philosophy means cutting-edge SDK versions often aren’t available through apt. SDKMAN bridges this gap, giving you instant access to the latest releases. You can switch between Java 8 for legacy applications and Java 21 for modern projects with a single command. This flexibility makes SDKMAN indispensable for developers managing diverse technology stacks.

Prerequisites for Installing SDKMAN on Debian 13

Before diving into the installation process, ensure your Debian 13 system meets the necessary requirements.

System Requirements

Your system needs Debian 13 (codenamed Trixie) installed and running. You’ll need a non-root user account with sudo privileges to install dependencies and modify system configurations. An active internet connection is essential for downloading SDKMAN and SDKs. Allocate at least 100MB of free disk space for the SDKMAN installation itself, though you’ll need considerably more for the SDKs you install later.

SDKMAN works with bash or ZSH shells, requiring version 3.2 or higher. Most Debian installations include a compatible shell by default. Verify your shell version by running bash --version in your terminal.

Required Software Dependencies

Three essential utilities must be installed before proceeding: curl, zip, and unzip. The curl utility downloads files from remote servers using various protocols. The zip and unzip packages handle compression and decompression of SDK archives. While wget can serve as an alternative to curl, most SDKMAN guides assume curl availability.

You’ll also benefit from having a text editor installed. Nano offers simplicity for beginners, vim provides power-user features, and gedit gives GUI-based editing. Choose whichever matches your comfort level.

Step-by-Step Installation Guide

Now let’s install SDKMAN on your Debian 13 system following these detailed steps.

Step 1: Update Your Debian 13 System

Start by updating your package lists and upgrading existing packages. Open your terminal and execute:

sudo apt update && sudo apt upgrade -y

This command performs two operations. The apt update refreshes repository metadata, ensuring you have the latest package information. The apt upgrade -y installs available updates, with the -y flag automatically confirming the upgrade. This process typically takes 2-5 minutes depending on how many packages need updating and your internet speed.

Keeping your system updated before installing new software prevents compatibility issues and ensures security patches are applied. Wait for the process to complete before proceeding to the next step.

Step 2: Install Required Dependencies

Install the three essential utilities SDKMAN needs:

sudo apt install curl zip unzip -y

This single command installs all three packages simultaneously. The -y flag bypasses confirmation prompts, streamlining the installation. The apt package manager automatically resolves dependencies and downloads the required files.

After installation completes, verify each utility installed correctly:

curl --version
zip --version
unzip --version

Each command should display version information. If any return “command not found,” rerun the installation command or check for typos. These tools are lightweight, typically consuming less than 10MB total disk space.

Step 3: Download and Execute SDKMAN Installation Script

Execute the official SDKMAN installation script:

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

Let’s break down this command. The curl utility fetches the installation script from the official SDKMAN server. The -s flag enables silent mode, suppressing progress meters and error messages for cleaner output. The pipe operator (|) redirects curl’s output directly to bash, which executes the script immediately.

During execution, the script performs several operations. It creates the $HOME/.sdkman directory structure in your home folder. Within this directory, it establishes subdirectories for candidates, archives, temporary files, and configuration. The script downloads SDKMAN’s core components, including the command-line interface and native binaries. Finally, it configures initialization scripts that will load SDKMAN into your shell environment.

The installation typically completes within 1-3 minutes, depending on your connection speed. You’ll see output indicating progress, including messages about creating directories and downloading files. When finished, you’ll receive a success message with instructions for the next step.

Step 4: Initialize SDKMAN in Current Session

Make SDKMAN available in your current terminal session:

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

The source command executes the initialization script within your current shell context. This loads SDKMAN’s functions and sets necessary environment variables. Without this step, the sdk command won’t be recognized.

The initialization script adds the SDKMAN binary directory to your PATH variable. It also defines shell functions for all SDKMAN commands. Additionally, it sets variables pointing to the SDKMAN installation directory and candidate locations.

Alternatively, you can simply open a new terminal window. The installation script automatically adds initialization code to your shell profile, so new terminal sessions will have SDKMAN loaded automatically.

Step 5: Make SDKMAN Persistent Across Sessions

Ensure SDKMAN loads automatically whenever you open a terminal. The installation script usually handles this, but verify by checking your .bashrc file:

grep -q 'sdkman-init.sh' ~/.bashrc || echo 'source "$HOME/.sdkman/bin/sdkman-init.sh"' >> ~/.bashrc

This command checks whether the initialization line already exists in .bashrc. If not, it appends the necessary code. After modifying .bashrc, reload the configuration:

source ~/.bashrc

This applies the changes immediately without requiring a logout. Future terminal sessions will automatically include SDKMAN functionality.

For ZSH users, the process is identical except you’ll modify .zshrc instead of .bashrc. The initialization code remains the same across different shells, ensuring consistent behavior.

Step 6: Verify SDKMAN Installation

Confirm SDKMAN installed correctly by checking its version:

sdk version

You should see output displaying both the script version and native version. For example:

SDKMAN!
script: 5.19.0
native: 0.5.0

If you see this output, congratulations—SDKMAN is installed and functioning properly. If you receive a “command not found” error, revisit the initialization steps. Ensure the initialization script ran successfully and your shell profile contains the correct source command.

You can also verify functionality by running:

sdk help

This displays available SDKMAN commands and usage information, providing another confirmation that installation succeeded.

Post-Installation Configuration

SDKMAN works well with default settings, but understanding configuration options helps tailor it to your needs.

Understanding SDKMAN Configuration File

SDKMAN stores configuration in ~/.sdkman/etc/config. This plain-text file contains key-value pairs controlling various behaviors. Open it with your preferred editor:

nano ~/.sdkman/etc/config

Several important parameters deserve attention. The sdkman_auto_answer setting determines whether SDKMAN automatically answers prompts. Setting it to true eliminates interactive confirmations. The sdkman_auto_selfupdate parameter controls whether SDKMAN updates itself automatically when new versions are available.

For users behind corporate firewalls or with SSL certificate issues, sdkman_insecure_ssl can be set to true to bypass certificate verification. However, this reduces security and should only be used when necessary.

Network timeout settings are particularly relevant for slow connections. The sdkman_curl_connect_timeout defines how long curl waits to establish a connection. The sdkman_curl_max_time sets the maximum time allowed for entire requests. Increasing these values helps prevent timeout errors on unreliable networks.

After making changes, save the file and restart your terminal or re-source your shell profile.

Custom Installation Directory (Optional)

While SDKMAN installs to $HOME/.sdkman by default, you can specify a custom location. This might be useful for shared systems or specific directory organization requirements.

To install to a custom directory:

export SDKMAN_DIR="/usr/local/sdkman" && curl -s "https://get.sdkman.io" | bash

This sets the SDKMAN_DIR environment variable before running the installation script. The script respects this variable and installs to the specified location.

Be aware that custom directories can introduce permission complications. Ensure your user has read, write, and execute permissions for the chosen directory. System directories like /usr/local may require sudo access, which can complicate SDK installations later.

For most users, the default home directory location is recommended. It avoids permission issues and keeps SDKMAN self-contained within your user space.

Using SDKMAN: Essential Commands

With SDKMAN installed, let’s explore the commands you’ll use regularly.

Viewing Available SDKs

List all available SDK candidates:

sdk list

This displays dozens of supported SDKs organized alphabetically. The output includes short descriptions helping you identify what each candidate provides.

For detailed information about a specific SDK’s available versions:

sdk list java

This command shows all Java distributions available through SDKMAN. The output includes vendor identifiers (like open for OpenJDK, oracle for Oracle JDK, amzn for Amazon Corretto), version numbers, and status indicators showing which versions are already installed and which is currently active.

The displayed information helps you choose appropriate versions for your projects. Pay attention to vendor codes and version numbers when installing specific JDK distributions.

Installing SDKs

Install an SDK using this syntax:

sdk install <candidate> <version>

For example, to install OpenJDK 11:

sdk install java 11.0.3-open

This downloads the specified Java version and installs it to ~/.sdkman/candidates/java/11.0.3-open. SDKMAN automatically configures it as your default Java version unless you specify otherwise.

To install the latest version without specifying a version number:

sdk install java

SDKMAN intelligently selects the newest stable release. After installation completes, it prompts whether to set the new version as default.

SDKs install to ~/.sdkman/candidates/ with subdirectories for each SDK type. This organized structure keeps different tools separated and manageable.

Switching Between SDK Versions

SDKMAN excels at version switching. For a temporary switch affecting only your current terminal session:

sdk use java 11.0.0-open

This changes the active Java version without affecting other terminals or future sessions. It’s perfect for testing how code behaves under different Java versions.

To permanently change your default version:

sdk default java 17.0.0-open

This sets Java 17 as the default for all new terminal sessions. Existing terminals retain their current versions until closed.

Check which version is currently active:

sdk current java

This displays the active version for Java specifically. To see current versions across all installed SDKs:

sdk current

For project-specific version management, create a .sdkmanrc file in your project root. This file specifies required SDK versions, and SDKMAN automatically switches to them when you enter the directory (if auto-environment is enabled).

Managing Installed SDKs

View all installed versions:

sdk list java

Installed versions appear with special markers in the output, making them easy to identify.

Remove an SDK version you no longer need:

sdk uninstall scala 3.4.2

This frees disk space by removing the specified version. Be careful not to uninstall versions your projects actively use.

Updating SDKMAN

Keep SDKMAN itself current:

sdk selfupdate

This checks for and installs SDKMAN updates. Forcing an update even if already current:

sdk selfupdate force

Refresh the candidate metadata cache to see newly released SDK versions:

sdk update

Run this periodically, especially when you know a new SDK version has been released but doesn’t appear in your listings.

Practical Examples: Installing Popular SDKs

Let’s install some commonly used development tools.

Installing Java Development Kit

Install OpenJDK:

sdk install java 21.0.1-open

Or Oracle JDK:

sdk install java 17.0.9-oracle

Verify the installation:

java -version

This confirms Java is properly configured and displays the active version.

Installing Build Tools

Install Gradle for building Java projects:

sdk install gradle 8.5

Install Maven for dependency management:

sdk install maven 3.9.6

Both tools become immediately available in your PATH.

Installing Frameworks

Install Spring Boot CLI for Spring application development:

sdk install springboot

Install the Kotlin compiler:

sdk install kotlin

These installations give you complete development environments with minimal effort.

Troubleshooting Common Issues

Even straightforward installations occasionally encounter problems. Here are solutions to common issues.

“sdk: command not found” Error

This indicates SDKMAN isn’t properly initialized in your shell. First, verify the initialization script exists:

ls -la ~/.sdkman/bin/sdkman-init.sh

If the file exists, manually source it:

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

Check whether your .bashrc contains the initialization line:

grep 'sdkman-init.sh' ~/.bashrc

If not, add it:

echo 'source "$HOME/.sdkman/bin/sdkman-init.sh"' >> ~/.bashrc

Then reload your configuration:

source ~/.bashrc

Network and Connection Errors

Encountering “Internet not reachable” errors despite having connectivity suggests timeout issues. Edit the SDKMAN configuration:

nano ~/.sdkman/etc/config

Increase timeout values:

sdkman_curl_connect_timeout=10
sdkman_curl_max_time=60

Save the file and try your operation again. For working behind proxies, ensure proxy environment variables are set correctly.

Enable offline mode when internet access is unavailable:

sdk offline enable

This allows using already-downloaded SDKs without attempting network connections.

Installation Failures

Missing temporary directory errors occur when SDKMAN can’t write temporary files. Create the directory manually:

mkdir ~/.sdkman/tmp

Permission issues typically stem from running installation commands with sudo when you shouldn’t, or vice versa. SDKMAN should be installed and run as a regular user, not root.

Insufficient disk space prevents SDK downloads. Check available space:

df -h ~

Free up space if necessary by uninstalling unused SDKs or cleaning system caches.

SDK Download Failures

When newly released SDK versions don’t appear, refresh candidate metadata:

sdk update

For corrupted downloads causing installation failures:

sdk flush archives

This clears the download cache, forcing fresh downloads on next installation attempt.

Best Practices for SDKMAN on Debian 13

Maximize SDKMAN’s effectiveness with these proven strategies.

Version Management Strategies

Create .sdkmanrc files in project repositories. These files specify required SDK versions, ensuring team members use consistent environments. Generate one automatically:

sdk env init

This creates .sdkmanrc based on currently active SDK versions. Commit this file to version control.

Maintain separate SDK versions for production and development environments. Use older, stable versions for production and newer releases for development and testing.

System Maintenance

Run sdk update weekly to refresh candidate metadata. This ensures you see newly released versions promptly.

Periodically review installed SDKs and remove unused versions:

sdk list java
sdk uninstall java 11.0.0-open

Monitor your .sdkman directory size:

du -sh ~/.sdkman

With multiple SDKs installed, this directory can grow to several gigabytes. Regular cleanup prevents excessive disk usage.

Security Considerations

Only install SDKs from trusted vendors. Review the vendor identifier before installation.

Keep SDKMAN updated to receive security patches:

sdk selfupdate

Avoid setting sdkman_insecure_ssl=true unless absolutely necessary. This disables SSL certificate verification, creating security vulnerabilities.

Integration with Development Workflow

Enable auto-environment switching for seamless version changes. Edit ~/.sdkman/etc/config:

sdkman_auto_env=true

Now SDKMAN automatically switches SDK versions when entering directories containing .sdkmanrc files.

For CI/CD pipelines, install SDKMAN in build containers. Use .sdkmanrc files to ensure builds use correct SDK versions consistently across environments.

Advanced Features

Power users will appreciate these advanced capabilities.

Offline Mode

Enable offline mode for working without internet:

sdk offline enable

This prevents SDKMAN from attempting network connections. It relies entirely on cached data and already-installed SDKs. Disable it when connectivity returns:

sdk offline disable

Auto-Environment Switching

Configure automatic version switching. Edit ~/.sdkman/etc/config:

sdkman_auto_env=true

With this enabled, SDKMAN detects .sdkmanrc files when you change directories. It automatically switches to specified SDK versions. Create .sdkmanrc in project roots:

sdk env init

This writes current SDK versions to .sdkmanrc, enabling automatic switching for anyone working on the project.

Installing Local Versions

Register custom or locally-built SDK versions with SDKMAN. This advanced feature supports development teams maintaining proprietary SDK modifications.

Uninstalling SDKMAN

Should you ever need to remove SDKMAN, follow these steps.

First, back up your configuration:

tar zcvf ~/sdkman-backup_$(date +%F-%kh%M).tar.gz -C ~/ .sdkman

Remove the SDKMAN directory:

rm -rf $HOME/.sdkman

Edit your .bashrc file and remove the SDKMAN initialization line:

nano ~/.bashrc

Find and delete the line containing sdkman-init.sh. Save the file and reload:

source ~/.bashrc

This completely removes SDKMAN from your system. Consider reinstalling rather than uninstalling if experiencing issues, as fresh installations often resolve problems.

Congratulations! You have successfully installed SDKMAN. Thanks for using this tutorial for installing SDKMAN on Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official SDKMAN website.