SDKman

March 19, 2025 ยท View on GitHub

SDK Manager installs and manages multiple versions of JDKs.

Originally it was just for JDK languages and their main build systems, but has in recent years extended to a wider list of support technologies:

  • JDK languages - Java, Groovy, Scala, Kotlin
  • JDK related build systems - Maven, Gradle, SBT, Ant
  • JDK based frameworks - Grails, Spring Boot, JBang
  • JDK based products - Hadoop, Spark, Flink, ActiveMQ, Tomcat, JMeter, VisualVM etc.

Install SDKman

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

Add SDKman to $PATH:

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

Will usually add something like this to the end of your $HOME/.bash_profile login profile script:

#THIS MUST BE AT THE END OF THE FILE FOR SDKMAN TO WORK!!!
export SDKMAN_DIR="/Users/hari/.sdkman"
[[ -s "/Users/hari/.sdkman/bin/sdkman-init.sh" ]] && source "/Users/hari/.sdkman/bin/sdkman-init.sh"

How It Works Under the Hood

Future shells will then automatically call /Users/hari/.sdkman/bin/sdkman-init.sh to add paths like this:

/Users/hari/.sdkman/candidates/scala/current/bin
/Users/hari/.sdkman/candidates/sbt/current/bin
/Users/hari/.sdkman/candidates/maven/current/bin
/Users/hari/.sdkman/candidates/java/current/bin
/Users/hari/.sdkman/candidates/groovy/current/bin
/Users/hari/.sdkman/candidates/gradle/current/bin

early in your $PATH list to default to using whatever version of each SDK SDKman has installed and switched to internally via symlinks in each case to:

/Users/hari/.sdkman/candidates/<name>/<version>

and are atomically switched to different versions by the sdk use command.

Using SDKman

https://sdkman.io/usage/

Help

Show list of commands:

sdk help

Update list of SDKs available to install:

sdk update

List all products SDKman can install

sdk list

(or sdk ls)

List Java versions

sdk list java

You will see a lot of different options for Java JVM implementations.

See:

TL;DR just use the Temurin community-driven OpenJDK distribution as it has the most versions. The Java.net one doesn't have older JVM releases you may need.

Install the latest Java SDK

sdk install java

(can also shorten to sdk i java)

You should see this puts the Java version first in your $PATH:

which java

/Users/hari/.sdkman/candidates/java/current/bin/java

Install another SDK version

Choose from the Version column string from the sdk list java output - so it's not quite a semver x.y.z due to the suffix differentiator between different JDK distributions.

version="21.0.4-tem"

sdk install java "$version"

Switch to use another SDK Version

sdk use java "$version"

List all the selected SDKs

sdk current

(or sdk c)

Output:

Using:

gradle: 7.3.3
groovy: 4.0.0
java: 21.0.4-tem
jbang: 0.119.0
maven: 3.8.4
pomchecker: 1.13.0
sbt: 1.6.2
scala: 3.1.1
visualvm: 2.1.10

List the Version of a Specific SDK

sdk current java

Output:

Using java version 21.0.4-tem

Delete a version of Java JDK installed

sdk rm java 21.0.4-tem

Deselecting java 21.0.4-tem...

Uninstalling java 21.0.4-tem...

Clean up temp space

sdk flush

Output:

       9 archive(s) flushed, freeing 619M       /Users/hari/.sdkman/archives.
      20 archive(s) flushed, freeing 104K       /Users/hari/.sdkman/tmp.
       9 archive(s) flushed, freeing  48K       /Users/hari/.sdkman/var/metadata.

Auto switch to the correct SDK using .sdkmanrc

Generate an .sdkmanrc file in the current directory:

sdk env init

Then either run this:

sdk env

or set sdkman_auto_env=true in $HOME/.sdkman/etc/config (this will only apply to new shells):

perl -pi -e 's/^\s*sdkman_auto_env=.*/sdkman_auto_env=true/' ~/.sdkman/etc/config
grep sdkman_auto_env ~/.sdkman/etc/config

(perl is more portable than sed -i which requires an arg on Mac)

Troubleshooting

Internet Not Reachable despite being online

If you get this error:

$ sdk list
==== INTERNET NOT REACHABLE! ===================================================

 Some functionality is disabled or only partially available.
 If this persists, please enable the offline mode:

   $ sdk offline

================================================================================

This command is not available while offline.

Check your connection like this:

curl -I https://api.sdkman.io/2/healthcheck

HTTP/1.1 200 OK
Server: nginx/1.19.10
Date: Thu, 27 Feb 2025 08:02:39 GMT
Content-Type: application/octet-stream
Content-Length: 24
Connection: keep-alive
Content-Type: text/plain

Check if SDKman can fetch the list manually:

curl -s https://api.sdkman.io/2/candidates/all

activemq,ant,asciidoctorj,ballerina,bld,bpipe,btrace,concurnas,connor,coursier,cuba,cxf,detekt,doctoolchain,flink,gaiden,gcn,grace,gradle,gradleprofiler,grails,groovy,groovyserv,hadoop,helidon,hsc,http4k,infrastructor,jarviz,java,jbake,jbang,jetty,jextract,jikkou,jmc,jmeter,joern,jreleaser,karaf,kcctl,ki,kobweb,kotlin,kscript,ktx,layrry,leiningen,liquibase,maven,mcs,micronaut,mulefd,mvnd,mybatis,neo4jmigrations,pierrot,pomchecker,quarkus,sbt,scala,scalacli,schemacrawler,skeletal,spark,springboot,sshoogr,taxi,test,tomcat,toolkit,vertx,visualvm,webtau,znai

Clear SDKman cache and then retry sdk list:

sdk flush candidates
rm -rf ~/.sdkman/var
sdk list

If all else fails:

rm -fr ~/.sdkman

and then re-install:

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

Can't Find Java Version to Install That is Clearly There

sdk current

Using:

java: 21.0.6-tem

sdk install java 21.0.6-tem

Stop! java 21.0.6-tem is not available. Possible causes:
 * is an invalid version
 * java 21.0.6-tem binaries are incompatible with your platform
 * java 21.0.6-tem has not been released yet

Tip: see all available versions for your platform:

  $ sdk list java 21.0.6-tem

Launch a new shell - it is a state problem with SDKman.