Install Scala 3.9, a JDK and an editor

To compile and run Scala 3.9 you need two programs on your computer: a JDK 17 or newer, and the scala command, which since Scala 3.5 is Scala CLI. In this track’s recorded runs, scala version reports Scala CLI 1.16.0 with Scala 3.9.0, and java -version reports Temurin 25.0.4.1.

Installing takes one command, Coursier’s cs setup, but three choices decide whether your runs match these pages: the JDK that runs your program, the Scala version each project compiles with, and the editor that reads the project. This lesson installs the tools and checks them, shows which JDK runs what, pins Scala 3.9.0 for a project, explains the WARNING lines that JDK 25 adds, and connects VS Code or IntelliJ IDEA.

A JDK, the scala command and an editor do three jobs

Each of the three pieces has one job, and one quick check that tells you it works:

The JDK comes first because everything else runs on it: Scala CLI is itself a Java program, and from Scala 3.8 on, compiling and running Scala need JDK 17 or newer. This track uses Eclipse Temurin 25, a long-term support build of JDK 25, but any JDK 17 or newer runs the same programs.

Scala CLI does not ship every compiler version inside it. The first time a project asks for a Scala version or a library, it downloads what it needs from Maven Central into a cache in your home folder, and later runs reuse the cache. That is why the first run of a new project takes longer than the rest, and why a computer without internet can run only what it has fetched before.

Install with Coursier, then check scala and java

The installation page of the Scala documentation recommends CoursierCoursier: The artifact fetcher and installer of the Scala world. cs setup installs the scala command and its tools, and cs java installs and selects JDKs., whose command is cs. Run the route for your system, then open a new terminal so that its PATH includes the new commands:

• macOS with Homebrew: brew install coursier && coursier setup.
• macOS without Homebrew, or Linux: download the cs binary for your processor as the installation page shows, make it executable with chmod +x cs, and run ./cs setup.
• Windows: download the Coursier installer from the installation page, run it, and answer its questions.

cs setup installs scala, scalac, sbt and scalafmt, adds them to your PATH, and installs a JVM if it finds none, after asking you. A version manager such as mise, which can install both Scala and JDKs, is another route: in a project folder, mise use scala@3.9.0 java@temurin-25 installs both and records them in the folder’s mise.toml. Step through the install, including the two ways back when a check fails:

Now the check. scala version names the Scala CLI behind the command and the Scala version it uses by default, and java -version names the JDK that your terminal finds first. This session shows everything the two commands printed on JDK 25, the first four lines included:

from session import run

# The check after an install: the scala command and the JDK, on JDK 25, with the launcher's warnings shown.
run("""
scala version
java -version
""", warnings=True)

$ scala version
WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
WARNING: sun.misc.Unsafe::objectFieldOffset has been called by scala.runtime.LazyVals$ (file:…/scala/3.9.0/libexec/scala-cli.jar)
WARNING: Please consider reporting this to the maintainers of class scala.runtime.LazyVals$
WARNING: sun.misc.Unsafe::objectFieldOffset will be removed in a future release
Scala code runner version: 1.16.0
Scala version (default): 3.9.0
$ java -version
openjdk version "25.0.4.1" LTS
OpenJDK Runtime Environment Temurin-25.0.4.1+1 (build 25.0.4.1+1-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.4.1+1 (build 25.0.4.1+1-LTS, mixed mode, sharing)

Leave the four WARNING lines for the next section. Scala code runner version: 1.16.0 is Scala CLI, and Scala version (default): 3.9.0 is the compiler it uses for a project that names no version. On your computer, cs setup installs the newest release, so after a fresh install the default is the newest Scala Next, 3.10.0 with Scala CLI 1.17.1, according to the 3.10.0 release notes. That is fine: the section after next pins 3.9.0 for each project, so the default never decides. The JDK’s first line ends with the build’s release date on a real terminal; the session leaves the date out.

The launcher and your program can run on different JDKs

The scala command is a Java program, and it starts another JVM for your program. The two need not be the same JDK. This session runs the version report of the previous lesson four times, changing one setting each time:

from session import run

# Which JDK runs what: the launcher runs on the first java on PATH, the program on JAVA_HOME or --java-home.
run("""
cd report
scala run . --server=false
export JAVA_HOME={jdk:21}
scala run . --server=false
export PATH="$JAVA_HOME/bin:$PATH"
scala run . --server=false
scala run . --server=false --java-home {jdk:17}
""", warnings=True)

$ cd report
$ scala run . --server=false
WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
WARNING: sun.misc.Unsafe::objectFieldOffset has been called by scala.runtime.LazyVals$ (file:…/scala/3.9.0/libexec/scala-cli.jar)
WARNING: Please consider reporting this to the maintainers of class scala.runtime.LazyVals$
WARNING: sun.misc.Unsafe::objectFieldOffset will be removed in a future release
WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::load has been called by com.sun.jna.Native in an unnamed module (file:…/scala/3.9.0/libexec/scala-cli.jar)
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled

Scala library   3.9.0
Java runtime    25.0.4.1 (Eclipse Adoptium)
Platform        Mac OS X, aarch64
$ export JAVA_HOME=…/java/temurin-21.0.12+101.0.LTS
$ scala run . --server=false
WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
WARNING: sun.misc.Unsafe::objectFieldOffset has been called by scala.runtime.LazyVals$ (file:…/scala/3.9.0/libexec/scala-cli.jar)
WARNING: Please consider reporting this to the maintainers of class scala.runtime.LazyVals$
WARNING: sun.misc.Unsafe::objectFieldOffset will be removed in a future release
WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::load has been called by com.sun.jna.Native in an unnamed module (file:…/scala/3.9.0/libexec/scala-cli.jar)
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled

Scala library   3.9.0
Java runtime    21.0.12.1 (Eclipse Adoptium)
Platform        Mac OS X, aarch64
$ export PATH="$JAVA_HOME/bin:$PATH"
$ scala run . --server=false
Scala library   3.9.0
Java runtime    21.0.12.1 (Eclipse Adoptium)
Platform        Mac OS X, aarch64
$ scala run . --server=false --java-home …/java/temurin-17.0.20+101
Scala library   3.9.0
Java runtime    17.0.20.1 (Eclipse Adoptium)
Platform        Mac OS X, aarch64

Follow the Java runtime line and the WARNING lines together:

1. With JDK 25 first on PATH and in JAVA_HOMEJAVA_HOME: An environment variable that names the folder of a JDK, the one that holds bin. Scala CLI runs your program on the JDK it names unless --java-home names another., both JVMs are JDK 25, and the warnings appear.
2. With only JAVA_HOME moved to JDK 21, the program reports 21, but the warnings stay: the launcher still runs on the java it found on PATH, JDK 25.
3. With JDK 21 first on PATH too, the warnings are gone, because the launcher now runs on JDK 21.
4. --java-home overrides JAVA_HOME for one run, and the program reports 17 while the launcher stays on 21.

So the launcher follows PATH, and your program follows JAVA_HOME, unless --java-home, or the directive //> using javaHome in a source file, names another JDK. A third way, //> using jvm 21 or --jvm 21, asks Scala CLI to fetch a JVM through Coursier; cs java --available lists the JDKs it can fetch. Step through the four runs:

The WARNING lines come from Scala CLI, not from your code

The eight lines are two warnings that JDK 24 introduced, and JDK 25 prints them too. The first four come from JEP 498: some code called a memory-access method of sun.misc.Unsafe, here scala.runtime.LazyVals inside scala-cli.jar. The next four come from JEP 472: some code loaded a native library without native access enabled, here JNA inside the same jar. Both name scala-cli.jar, so they describe the tool, and your program is not involved. They are harmless today, and JDKs older than 24 do not print them at all: with the launcher on JDK 21, the third run showed none.

To switch them off on JDK 25, give every java that Scala CLI starts the two options that JEP 498 and JEP 472 name, through the JDK_JAVA_OPTIONS environment variable, which the java launcher adds to its command line:

from session import run

# The launcher's two JDK 25 warnings switched off for every JVM that the scala command starts.
run("""
cd report
export JDK_JAVA_OPTIONS="--sun-misc-unsafe-memory-access=allow --enable-native-access=ALL-UNNAMED"
scala run . --server=false
""", warnings=True)

$ cd report
$ export JDK_JAVA_OPTIONS="--sun-misc-unsafe-memory-access=allow --enable-native-access=ALL-UNNAMED"
$ scala run . --server=false
NOTE: Picked up JDK_JAVA_OPTIONS: --sun-misc-unsafe-memory-access=allow --enable-native-access=ALL-UNNAMED
NOTE: Picked up JDK_JAVA_OPTIONS: --sun-misc-unsafe-memory-access=allow --enable-native-access=ALL-UNNAMED
NOTE: Picked up JDK_JAVA_OPTIONS: --sun-misc-unsafe-memory-access=allow --enable-native-access=ALL-UNNAMED
Scala library   3.9.0
Java runtime    25.0.4.1 (Eclipse Adoptium)
Platform        Mac OS X, aarch64

The warnings are gone, but each JVM now prints a NOTE line instead, because the java command reminds you whenever it reads JDK_JAVA_OPTIONS. The three notes come from the launcher, from the compiler, which --server=false starts in a JVM of its own, and last from your program. Whether eight lines or three bother you more is your call; the sessions of this track simply leave the warnings out.

Pin Scala 3.9.0 in each project

A using directiveusing directive: A comment line that starts with //> using and configures Scala CLI from inside the sources, for example //> using scala 3.9.0 to pin the compiler version. is a comment line that starts with //> using and configures Scala CLI from inside the sources. The installation page suggests keeping a project’s directives together in a file named project.scala. One line pins the compiler, whatever the default of your scala command is:

//> using scala 3.9.0

The session runs a project pinned to 3.9.0, then a copy pinned to 3.10.0, on a computer without network access that has never used 3.10.0:

from session import run

# A project that names its Scala version, then one that asks for a version this computer has never downloaded.
run("""
cd pin
cat project.scala
scala run . --server=false
cd ../pin-newer
cat project.scala
!scala run . --server=false
""", downloads="first")

$ cd pin
$ cat project.scala
//> using scala 3.9.0
$ scala run . --server=false
Scala library   3.9.0
Java runtime    25.0.4.1 (Eclipse Adoptium)
Platform        Mac OS X, aarch64
$ cd ../pin-newer
$ cat project.scala
//> using scala 3.10.0
$ scala run . --server=false
Downloading https://repo1.maven.org/maven2/org/scala-lang/scala3-library_3/maven-metadata.xml
Failed to download https://repo1.maven.org/maven2/org/scala-lang/scala3-library_3/maven-metadata.xml
[22 more lines of download attempts not shown]
[error]  Cannot find matching Scala version for '3.10.0'
You can only choose one of the 3.x, 2.13.x, and 2.12.x. versions.
The latest supported stable versions are 2.12.21, 2.13.18, 3.8.4.
In addition, you can request compilation with the last nightly versions of Scala,
by passing the 2.nightly, 2.12.nightly, 2.13.nightly, or 3.nightly arguments.
Specific Scala 2 or Scala 3 nightly versions are also accepted.
You can also request the latest Scala 3 LTS by passing lts or 3.lts.
[exit status 1]

The first project compiled with 3.9.0, as pinned. The second failed, and its last message is misleading: Cannot find matching Scala version for '3.10.0' sounds as if 3.10.0 did not exist, and the list of “latest supported” versions that follows stops at 3.8.4. The real cause is in the first lines: Scala CLI tried to download the list of Scala 3 versions from Maven Central, and every attempt failed. With a network the same command downloads 3.10.0 once, caches it, and runs. The message also names a shortcut, lts: //> using scala lts asks for the newest Scala LTS release.

Pin an exact version such as 3.9.0 rather than lts. An exact pin gives the same compiler on every computer and in CI until you change the line, while lts moves to 3.9.1 when it is released. On the command line, --scala 3.9.0 does the same for one run.

Editors open the project through BSP

Editors do not compile Scala themselves. They ask a build tool through BSPBSP: The Build Server Protocol: the way an editor such as VS Code with Metals or IntelliJ IDEA asks a build tool to compile a project and report its errors., the Build Server Protocol, and Scala CLI acts as that build tool for its projects. scala setup-ide . writes the connection file that an editor reads, and so does the first scala run, compile or test of a project:

from session import run

# What an editor reads to open a Scala CLI project: the connection file that scala setup-ide writes.
run("""
cd ide
scala setup-ide .
cat .bsp/scala.json
""")

$ cd ide
$ scala setup-ide .
Wrote configuration file for ide in: .bsp/scala.json
$ cat .bsp/scala.json
{
  "name": "scala",
  "argv": [
    "…/java/temurin-25.0.4+101.0.LTS/bin/java",
    "-jar",
    "…/scala/3.9.0/libexec/scala-cli.jar",
    "--cli-default-scala-version",
    "3.9.0",
    "--repository",
    "file://…/scala/3.9.0/maven2",
    "--prog-name",
    "scala",
    "--skip-cli-updates",
    "bsp",
    "--json-options",
    ".scala-build/ide-options-v2.json",
    "--json-launcher-options",
    ".scala-build/ide-launcher-options.json",
    "--envs-file",
    ".scala-build/ide-envs.json",
    "."
  ],
  "version": "1.16.0",
  "bspVersion": "2.1.1",
  "languages": [
    "scala",
    "java"
  ]
}

The file tells the editor how to start Scala CLI as a build server: the java of the JDK that ran setup-ide, the scala-cli.jar of the installation, the default Scala version, and the bsp command. Because it records that JDK’s path, run scala setup-ide . again after you switch JDKs. The two editors open the folder like this:

• VS Code: install the Metals extension, then open the project folder (code .). Metals starts, imports the project, and puts run and debug buttons above each @main method. Metals itself runs on a JDK 17 or newer by default and compiles your project with the JDK of JAVA_HOME; its settings name both.
• IntelliJ IDEA: install the Scala plugin, then choose File > Open and select the project folder. IntelliJ finds the .bsp folder and imports the project through BSP; when the import works, a BSP icon in the bottom right corner shows the connection.

Practise: run the setup check on your computer

This program checks the three things the rest of the track needs: a JDK 17 or newer, Scala 3.9.x and UTF-8 as the JDK’s default charset. For each check that fails it prints the fix, and it ends with a non-zero exit status, so a script can test it. Copy it into an empty folder, together with a project.scala that pins 3.9.0, and run scala run . there:

// Checks the three things this track's programs need, and says how to fix each one that fails.
import java.nio.charset.Charset

case class Check(name: String, ok: Boolean, fix: String)

def checks(): List[Check] =
  val jdk = Runtime.version().feature()
  val scalaVersion = scala.util.Properties.versionNumberString
  val charset = Charset.defaultCharset().name()
  List(
    Check(s"JDK $jdk (17 or newer)", jdk >= 17, "install a JDK 17 or newer and point JAVA_HOME at it"),
    Check(s"Scala $scalaVersion (3.9.x)", scalaVersion.startsWith("3.9."), "add //> using scala 3.9.0 to project.scala"),
    Check(s"default charset $charset", charset == "UTF-8", "use JDK 18 or newer, or set the locale to UTF-8")
  )

@main def setupCheck(): Unit =
  val results = checks()
  for c <- results do
    if c.ok then println(s"ok    ${c.name}") else println(s"FIX   ${c.name}: ${c.fix}")
  val failed = results.count(!_.ok)
  if failed == 0 then println("Ready for this track.")
  else
    println(s"$failed of ${results.size} checks failed.")
    sys.exit(1)

Here it is on JDK 25, and then on JDK 17 with the C locale:

from session import run

# The setup check on JDK 25, then on JDK 17 with the C locale, where the default charset is not UTF-8.
run("""
cd setup-check
scala run . --server=false
export JAVA_HOME={jdk:17}
export LC_ALL=C
export LANG=C
!scala run . --server=false
""")

$ cd setup-check
$ scala run . --server=false
ok    JDK 25 (17 or newer)
ok    Scala 3.9.0 (3.9.x)
ok    default charset UTF-8
Ready for this track.
$ export JAVA_HOME=…/java/temurin-17.0.20+101
$ export LC_ALL=C
$ export LANG=C
$ scala run . --server=false
ok    JDK 17 (17 or newer)
ok    Scala 3.9.0 (3.9.x)
FIX   default charset US-ASCII: use JDK 18 or newer, or set the locale to UTF-8
1 of 3 checks failed.
[exit status 1]

The second run fails one check. Before JDK 18, the JDK chose its default charset from the system: JEP 400 notes that macOS used UTF-8 unless the POSIX C locale was set, and Windows usually used a code page such as windows-1252. Since JDK 18 the default is UTF-8 everywhere. So the fix is a newer JDK, or a UTF-8 locale for JDK 17. Your run should end with Ready for this track.

Then test the five ideas of the lesson, from the three pieces to the editor’s connection file. Each answer is explained the moment you give it:

Interview questions

Fresher · Why does Scala need a JDK, and which version does Scala 3.9 need?

Scala compiles to JVM bytecode, so a JVM must run every Scala program, and the Scala tools themselves are JVM programs: the compiler, and the scala command, which is Scala CLI, run on a JVM too. A JDK provides that JVM plus tools such as javap. From Scala 3.8 on, which includes 3.9 LTS, compiling and running Scala need JDK 17 or newer; the compiled classes have class-file version 61, the version of Java SE 17, so an older JVM refuses them. JDK 21 and 25 work as well. Any vendor’s build of the right version runs the same programs; this track uses Eclipse Temurin 25. Of the lines still maintained, only the older 3.3 LTS still produces bytecode for JDK 8.

Key takeaways

• A JDK 17 or newer runs everything, the scala command is Scala CLI and fetches compilers and libraries on first use, and an editor reads the project through BSP.
• cs setup installs the scala command and its tools; check them in a new terminal with scala version and java -version.
• The launcher runs on the first java on PATH, and your program on the JDK of JAVA_HOME unless --java-home or a directive names another; JDK 25’s WARNING lines come from the launcher.
• //> using scala 3.9.0 in project.scala pins the compiler for a project, and a version that is not in the cache needs one download, which fails with a misleading message when offline.
• scala setup-ide . writes .bsp/scala.json, which VS Code with Metals and IntelliJ IDEA read to open the project.