sbt 2 is now available!

This post covers work done under the Sovereign Tech Fund investment umbrella: sbt 2 Stable Release and Maintenance. The work is coordinated by the Scala Center.

After five years of development, sbt 2 is out. Since the experimental sudori part 1 blog post in 2021, more than 82 people have contributed to the project. We would like to thank community and corporate contributors, Scala Center, and Sovereign Tech Fund for their support.

What’s new in sbt 2?

sbt 2 is a new version of sbt. If you’re familiar with sbt 1.x, hopefully the jump is not too far, but we have pushed sbt to the modern standard. The headline features are:

• sbt 2.x uses Scala 3.8.4 for build definitions and plugins (Both sbt 1.x and 2.x are capable of building Scala 2.x and 3.x), which requires minimum JDK 17
• Uses sbtn (native-image client) for faster startup.
• test changed to incremental test.
• Local/remote cache system that is Bazel-compatible. compile and test are both rewritten to be cachable tasks.
• Project matrix, which was available via plugin in sbt 1.x, is in-sourced in sbt 2.x.
• Client-side run.
• Client-side console.
• New documentation.

For more details, please check out sbt 2.0 changes summary and the Scala Days 2025 talk sbt 2.0: go big from 2025.

How do I get started with sbt 2?

The sbt version used for your build is upgraded by putting the following in project/build.properties:

sbt.version=2.0.1

This mechanism allows that sbt 2.0.1 is used only for the builds that you want.

Download the official sbt runner from SDKMAN, or download from https://github.com/sbt/sbt/releases/tag/v2.0.1 to upgrade the sbt shell script, sbtn, and the launcher.

Repopulating the plugin ecosystem

Major plugins are already available on sbt 2.x.

Under the sbt 2 workstream, Anatolii from Scala Center has created the sbt2-compat plugin, which bridges the source-level differences between sbt 1.x and 2.x. This allows cross-building of a plugin, aiding the migration process. Also under the STA workstream, Rikito Taniguchi from VirtusLab has cross built Scala.JS plugin to sbt 2.x (scala-js#5314).

This means we can now cross build JVM / JS / Native using sbt 2.x!

Client-server by default

The sbt runner script is capable of running either sbt 1.x build or 2.x build. When the sbt runner detects an sbt 2.x build, it will now launch the native sbtn client. This will start the sbt server as a background process, and sbtn will send the command. This means that, if you wish, you can use your system shell:

$ sbt compile
$ sbt test

The client program is gradually getting richer. For example, it can launch Scala REPL when the console task is detected. This keeps sbt server available for other tasks.

Project matrix

sbt 2.x ships with project matrix, which lets you cross build multiple versions of Scala and multiple platforms (JVM, JS, and Native). With projectMatrix, you declare the platform rows you want in one place. Each row becomes a normal subproject. For example, this defines JVM, Scala.js, and Scala Native rows:

lazy val core = (projectMatrix in file("core"))
  .settings(
    name := "core",
  )
  .jvmPlatform(...)
  .nativePlatform(...)
  .jsPlatform(...)

For Scala.js and Scala Native, add the plugins:

// project/plugins.sbt
addSbtPlugin("org.scala-native" % "sbt-scala-native" % "0.5.11")

addSbtPlugin("org.scala-js" % "sbt-scalajs" % "1.22.0")

Using cross-published libraries

In sbt 1.x, Scala.js and Scala Native builds required %%% for dependencies, so that the platform-specific suffix is included in the artifact name. In sbt 2.x, cross-built dependencies can be written with %%, just like JVM libraries:

libraryDependencies += "org.typelevel" %% "cats-effect" % "3.5.4"

See Cross building and Cross building setup for more details.

Let us know what you think

Have you tried sbt 2? Let us know what you think in the discussion forum. If you find a bug, please let us know as well.

Participation

The Scala Center has been entrusted with coordinating the commissioned Scala work for the Sovereign Tech Fund. The Scala Center is an independent, not-for-profit center sponsored by corporate members and individual backers like you to promote and facilitate Scala. If you would like to participate and/or see more of these types of efforts, please reach out to your manager to see if your company can donate engineering time or membership to the Scala Center.

See The Scala Center Fundraising Campaign for more details.

sbt 2 was brought to you by many contributors, including those who contributed to sbt 1.x series, migrating plugins, but according to git shortlog -sn --no-merges 00eba85d98c854527125ae1655b5332c19b5afd8...733bcfb23997930915b563e7d27b1a1f6c0490da --not 1.11.x and git shortlog -sn --group=author --group=trailer:co-authored-by --no-merges 242bd18d30c418620024d089b587f6d263d34247...v2.0.0 --not 1.12.x:

545 Eugene Yokota (eed3si9n)
217 Kenji Yoshida (xuwei-k)
146 Adrien Piquerez
51  Jerry Tan (friendseeker)
37  MkDev11
34  bitloi
30  Scala Steward
21  calm329
16  Anatolii Kmetiuk
15  dependabot[bot]
14  Yasuhiro Tatsuno
13  E.G
11  Pandaman
10  João Ferreira
9   Anton Sviridov
9   Brian Hotopp
8   Aleksandra Zdrojowa
7   Dream
7   GlobalStar117
7   Matt Dziuban
5   Dairus
4   Martin Duhem
4   john0030710
3   Angel98518
3   Brice Jaglin
3   Li Haoyi
3   gayanMatch
2   Ali Rashid
2   Billy Autrey
2   BitToby
2   Damian Reeves
2   Daniil Sivak
2   Dmitrii Naumenko
2   Douglas Ma
2   Frank S. Thomas
2   Jame4u
2   Josh Soref
2   Kamil Podsiadło
2   Marco Zühlke
2   Matthew de Detrich
2   Matthias Kurz
2   Michał Pawlik
2   Miguel Vilá
2   NeedmeFordev
2   Pluto
2   Renzo
2   Rikito Taniguchi
2   SID
2   Satoshi Dev
2   byteforge
2   circlecrystalin
2   it-education-md
1   Albert Meltzer
1   Deborah Funmilola Olaboye
1   Eve
1   Francluob
1   Guillaume Massé
1   Hamza Remmal
1   Hugo van Rijswijk
1   Idan Ben-Zvi
1   Jakub Kozłowski
1   James Roper
1   Karl Yngve Lervåg
1   Lazz
1   Lukas Rytz
1   Nikita Vilunov
1   OlegYch
1   Pegasus
1   Rex Kerr
1   Roberto Tyley
1   Saber
1   SalesforcePeak
1   SlowBrainDude
1   Zainab Ali
1   bohdansolovie
1   chrisrock1124
1   corevibe555
1   dev-miro26
1   dive2tech
1   fireXtract
1   kijuky
1   nathanlao

Thanks to everyone who’s helped improve sbt and Zinc by using them, reporting bugs, improving our documentation, porting builds, porting plugins, and submitting and reviewing pull requests.