These are some notes for my future self, to keep track of a slightly modified version of the official Install Scala documentation.

Install coursier

Coursier is a versatile tool, capable of

  • installing software (like brew)
  • switching between java versions (like sdkman)

There is a brew formula to install coursier, but it also installs a JDK that takes precedence over the one installed by coursier, see this issue

❯ java -version
openjdk version "26.0.2" 2026-07-21
OpenJDK Runtime Environment Homebrew (build 26.0.2)
OpenJDK 64-Bit Server VM Homebrew (build 26.0.2, mixed mode, sharing)

❯ cs java-home
/Users/yann.moisan/Library/Caches/Coursier/arc/https/cdn.azul.com/zulu/bin/zulu25.36.15-ca-jdk25.0.4-macosx_aarch64.tar.gz/zulu25.36.15-ca-jdk25.0.4-macosx_aarch64/Contents/Home

❯ which -a java
/opt/homebrew/opt/openjdk/bin/java
/usr/bin/java

❯ echo $JAVA_HOME
/Users/yann.moisan/Library/Caches/Coursier/arc/https/cdn.azul.com/zulu/bin/zulu25.36.15-ca-jdk25.0.4-macosx_aarch64.tar.gz/zulu25.36.15-ca-jdk25.0.4-macosx_aarch64/Contents/Home

So just download cs and put it on your path:

curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-aarch64-apple-darwin.gz | gzip -d > cs
chmod +x cs

Setup your shell

After installing coursier, it is recommended to run the cs setup command. Besides configuring your shell, this is also the step that actually installs Scala: cs setup installs coursier itself plus a set of standard Scala tools (scala, scala-cli, sbt, ammonite, scalafmt, …).

According to the docs, though:

It’s mostly made to easily setup CI environments, rather than switch JVMs.

Indeed, it modifies your .zprofile with a fixed path to a given JDK:

export JAVA_HOME="/Users/yamo/Library/Caches/Coursier/arc/https/github.com/AdoptOpenJDK/openjdk11-binaries/releases/download/jdk-11.0.11%252B9/OpenJDK11U-jdk_x64_mac_hotspot_11.0.11_9.tar.gz/jdk-11.0.11+9/Contents/Home"

I prefer to run it with the extra --env argument (cs setup --env) and edit .zshrc myself to add these two lines:

export PATH="$PATH:$HOME/Library/Application Support/Coursier/bin"
eval "$(cs java --jvm 25 --env)"

so that I can easily change my default java version. Note that eval "$(cs java --jvm N --env)" only changes JAVA_HOME for the current shell session, which is why the .zshrc line above sets a persistent default for new sessions.

Switch java version

❯ eval "$(cs java --jvm 25 --env)"
❯ java -version
openjdk version "25.0.4" 2026-07-21 LTS
OpenJDK Runtime Environment Temurin-25.0.4+7 (build 25.0.4+7-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.4+7 (build 25.0.4+7-LTS, mixed mode)
❯ eval "$(cs java --jvm 26 --env)"
❯ java -version
openjdk version "26.0.2.1" 2026-08-18
OpenJDK Runtime Environment Temurin-26.0.2.1+1 (build 26.0.2.1+1)
OpenJDK 64-Bit Server VM Temurin-26.0.2.1+1 (build 26.0.2.1+1, mixed mode)

Wrap-up

So, to sum up: download cs directly rather than through brew, run cs setup --env once to install coursier and the standard Scala tools, then wire eval "$(cs java --jvm N --env)" into your shell config for a default JDK and re-run it whenever you want to switch versions.