Skip to content

various updates to JDK compat guide #3230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 12, 2025
Merged

various updates to JDK compat guide #3230

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
acd57a1
various updates to JDK compat guide
SethTisue Nov 11, 2025
25a3a0b
Scala 3.9 is next LTS
SethTisue Nov 11, 2025
e27795d
fix in response to review feedback
SethTisue Nov 12, 2025
a696d5c
fix in response to review feedback
SethTisue Nov 12, 2025
f8670ff
separate Scala 3 and 2, and make 3 most prominent
SethTisue Nov 12, 2025
89e5cb6
tweak
SethTisue Nov 12, 2025
002f8f0
tweak
SethTisue Nov 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 40 additions & 26 deletions _overviews/jdk-compatibility/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,46 @@ title: JDK Compatibility
permalink: /overviews/jdk-compatibility/overview.html
---

Scala's primary platform is the Java Virtual Machine (JVM). (Other supported platforms: [Scala.js](https://www.scala-js.org/), [Scala Native](https://scala-native.org/).)
Scala's primary platform is the Java Virtual Machine (JVM). Other supported platforms are [Scala.js](https://www.scala-js.org/) and [Scala Native](https://scala-native.org/).

Sometimes new JVM and JDK (Java Development Kit) versions require us to update Scala to remain compatible.

## Scala compatibility table
## Scala 3 compatibility

Minimum Scala versions:
Scala 3 versions from 3.3 LTS through Scala 3.7 support JDK 8 and above.

| JDK | 3 | 3 LTS | 2.13 | 2.12 | 2.11 |
|:-----------:|:--------:|:--------:|:---------:|:---------:|:----------:|
| 25 (LTS) | 3.7.1 | 3.3.6 | 2.13.17 | 2.12.21* | |
| 21 (LTS) | 3.4.0 | 3.3.1 | 2.13.11 | 2.12.18 | |
| 17 (LTS) | 3.0.0 | 3.3.0 | 2.13.6 | 2.12.15 | |
| 11 (LTS) | 3.0.0 | 3.3.0 | 2.13.0 | 2.12.4 | 2.11.12 |
| 8 (LTS) | 3.0.0 | 3.3.0 | 2.13.0 | 2.12.0 | 2.11.0 |
As per [this blog post](https://www.scala-lang.org/news/next-scala-lts-jdk.html),
Scala 3.8 will have a new minimum JDK version of 17.

The next Scala 3 LTS release will be Scala 3.9.

Minimum Scala 3 versions for each JDK:

| JDK | 3.8* | 3.4+ | 3.3 LTS |
|:-----------:|:------:|:--------:|:--------:|
| 25 (LTS) | 3.8.0* | 3.7.1 | 3.3.6 |
| 21 (LTS) | 3.8.0* | 3.4.0 | 3.3.1 |
| 17 (LTS) | 3.8.0* | 3.4.0 | 3.3.0 |
| 11 (LTS) | | 3.4.0 | 3.3.0 |
| 8 (LTS) | | 3.4.0 | 3.3.0 |

\* = forthcoming; support available in [nightly builds](https://docs.scala-lang.org/overviews/core/nightlies.html)

Even when a version combination isn't listed as supported, most features might still work.

Using the latest patch version of your chosen Scala version line is always recommended.

## Scala 2 compatibility

Minimum Scala 2 versions for each JDK:

| JDK | 2.13 | 2.12 |
|:-----------:|:---------:|:---------:|
| 25 (LTS) | 2.13.17 | 2.12.21* |
| 21 (LTS) | 2.13.11 | 2.12.18 |
| 17 (LTS) | 2.13.6 | 2.12.15 |
| 11 (LTS) | 2.13.0 | 2.12.4 |
| 8 (LTS) | 2.13.0 | 2.12.0 |

\* = forthcoming; support available in [nightly builds](https://docs.scala-lang.org/overviews/core/nightlies.html)

Expand All @@ -34,7 +59,7 @@ Minimum working versions:

| JDK | scala-cli | sbt | mill |
|:-----------:|:-----------:|:---------:|:-----------|
| 25 (LTS) | forthcoming | 1.9.0 | 1.0.0 |
| 25 (LTS) | 1.10.0 | 1.9.0 | 1.0.0 |
| 21 (LTS) | 1.0.0 | 1.9.0 | 0.11.5 |
| 17 (LTS) | 1.0.0 | 1.6.0 | 0.7.0 |
| 11 (LTS) | 1.0.0 | 1.1.0 | 0.1.5 |
Expand All @@ -50,11 +75,11 @@ Using a different build tool, such as Gradle or Maven? We invite pull requests a

## Running versus compiling

JDK 8, 11, 17, 21, and 25 are all reasonable choices both for *compiling* and *running* Scala code.
JDK 17, 21, and 25 are all good choices both for *compiling* and *running* Scala code.

Since the JVM is normally backwards compatible, it is usually safe to use a newer JVM for *running* your code than the one it was compiled on, especially if you are not using JVM features designated "experimental" or "unsafe".
JDK 8 and 11 are also possible choices. As of 2025, these versions remain in use at some shops, but usage has declined greatly and many projects are dropping support. If you compile on JDK 17+ but want to allow your users to stay on 8, use `--release 8` to avoid using APIs and features that don't exist in 8. Another option is to use a newer JDK for your daily work but do release builds on JDK 8.

JDK 8 remains in use at some shops (as of 2023), but usage is declining and some projects are dropping support. If you compile on JDK 11+ but want to allow your users to stay on 8, additional care is needed to avoid using APIs and features that don't exist in 8. (For this reason, some Scala developers use a newer JDK for their daily work but do release builds on JDK 8.)
Since the JVM is normally backwards compatible, it is usually safe to use a newer JVM for *running* your code than the one it was compiled on, especially if you are not using JVM features designated "experimental" or "unsafe".

As per [this blog post](https://www.scala-lang.org/news/next-scala-lts-jdk.html), Scala 3.8 will have a new minimum JDK version of 17.

Expand All @@ -74,15 +99,13 @@ In almost every case, you're free to use the JDK and JVM of your choice.

JDK 8 users typically use the Oracle JDK or some flavor of OpenJDK.

Most JDK 11+ users are using OpenJDK, or GraalVM which runs in the context of OpenJDK. GraalVM performs well on the Scala benchmarks, and it benefits from GraalVM runtime and runs faster too.

OpenJDK comes in various flavors, offered by different providers. We typically build and test Scala using [Temurin](https://adoptium.net) or [Zulu](https://www.azul.com/downloads/), but the differences are unlikely to matter to most users.

## JDK 11 compatibility notes

The Scala test suite and Scala community build are green on JDK 11.

In general, Scala works on JDK 11+, including GraalVM, but may not take special advantage of features that were added after JDK 8.
In general, Scala works on JDK 11+, but may not take special advantage of features that were added after JDK 8.

For example, the Scala compiler does not enforce the restrictions of the Java Platform Module System, which means that code that typechecks may incur linkage errors at runtime. Scala 2.13.x will eventually provide [rudimentary support](https://github.com/scala/scala/pull/7218) for this (perhaps only in nightlies built on JDK 11).

Expand Down Expand Up @@ -132,8 +155,6 @@ For information on timing of the forthcoming release, see:

* https://contributors.scala-lang.org/t/scala-2-12-21-release-planning/6753

<!-- TODO For sbt users, sbt 1.9.0 is the first version to support JDK 21.-->

For possible Scala 3 issues, see the [area:jdk](https://github.com/scala/scala3/labels/area%3Ajdk) and [compat:java](https://github.com/scala/scala3/labels/compat%3Ajava) labels in [the Scala 3 issue tracker](https://github.com/scala/scala3/issues).

For possible Scala 2 issues, see the [jdk11](https://github.com/scala/bug/labels/jdk11), [jdk17](https://github.com/scala/bug/labels/jdk17), [jdk21](https://github.com/scala/bug/labels/jdk21), and [jdk25](https://github.com/scala/bug/labels/jdk25) labels in [the Scala 2 bug tracker](https://github.com/scala/bug/issues).
Expand All @@ -147,10 +168,3 @@ A few sbt plugins are offering support for GraalVM Native Image compilation:

- [sbt-native-packager](https://www.scala-sbt.org/sbt-native-packager/formats/graalvm-native-image.html)
- [sbt-native-image](https://github.com/scalameta/sbt-native-image)

## Scala 3

At present, both Scala 3.3 LTS and Scala Next support JDK 8, as well as 11 and beyond.

As per [this blog post](https://www.scala-lang.org/news/next-scala-lts-jdk.html),
Scala 3.8 will have a new minimum JDK version of 17. This can already be tested in Scala 3.8 nightlies.