Configuring Scala

Learn how to configure Scala versions and compiler options in your sbt project

This guide covers how to configure Scala versions, compiler options, and switch between different Scala versions in your sbt build.

Setting the Scala Version

The most basic Scala configuration is setting the version using the scalaVersion key:

build.sbt

scalaVersion := "3.3.1"

For Scala 2:

build.sbt

scalaVersion := "2.13.12"

The scalaVersion setting determines which version of the Scala compiler is used for building your project.

Scala Organization

By default, sbt uses org.scala-lang as the Scala organization. This is an advanced setting for Scala language clones:

build.sbt

scalaOrganization := "org.scala-lang"

Only modify scalaOrganization if you’re using a custom Scala distribution. Standard projects should use the default value.

Configuring Compiler Options

The scalacOptions task controls options passed to the Scala compiler:

build.sbt

scalacOptions ++= Seq(
  "-deprecation",
  "-feature",
  "-unchecked",
  "-Xlint",
  "-Ywarn-dead-code"
)

Common Scala 2 Compiler Options

Warnings

scalacOptions ++= Seq(
  "-deprecation",           // Emit warning for deprecations
  "-feature",               // Emit warning for features
  "-unchecked",             // Enable detailed unchecked warnings
  "-Xlint",                 // Enable recommended warnings
  "-Ywarn-dead-code",       // Warn when dead code is identified
  "-Ywarn-numeric-widen",   // Warn when numeric types are widened
  "-Ywarn-value-discard"    // Warn when non-Unit values are discarded
)

Common Scala 3 Compiler Options

build.sbt

scalacOptions ++= Seq(
  "-deprecation",
  "-feature",
  "-explain",              // Explain errors in more detail
  "-Xfatal-warnings",     // Fail the compilation if there are warnings
  "-Yexplicit-nulls",     // Enable explicit null tracking
  "-Ysafe-init"           // Ensure safe initialization
)

Scala Binary Version

The scalaBinaryVersion is automatically derived from scalaVersion and describes binary compatibility:

// When scalaVersion := "2.13.12"
// scalaBinaryVersion will be "2.13"

// When scalaVersion := "3.3.1"
// scalaBinaryVersion will be "3"

The binary version is used by the %% operator for library dependencies to ensure binary compatibility.

Cross-Building

For projects that need to support multiple Scala versions, use crossScalaVersions:

build.sbt

scalaVersion := "3.3.1"

crossScalaVersions := Seq("2.13.12", "3.3.1")

Then use the + command prefix:

# Compile for all Scala versions
sbt +compile

# Test for all Scala versions
sbt +test

# Publish for all Scala versions
sbt +publish

Switching Scala Versions

Use the ++ command to switch Scala versions:

1. Switch to a specific version

   sbt "++2.13.12"
   
2. Switch and run a command

   sbt "++2.13.12 compile"
   
3. Force a version (not in crossScalaVersions)

   sbt "++2.12.18!"
   

   The ! forces the version even if it’s not in crossScalaVersions.

Using a Local Scala Installation

You can use a local Scala installation instead of fetching from Maven:

build.sbt

scalaHome := Some(file("/path/to/scala/home"))

Or from the command line:

sbt "++/path/to/scala/home"

Scala Instance Configuration

Advanced users can configure the Scala instance directly:

build.sbt

autoScalaLibrary := true  // Automatically add scala-library dependency
managedScalaInstance := true  // Use managed Scala instance

Configuration Per Configuration

You can set different compiler options for different configurations:

build.sbt

// Different options for Test configuration
Test / scalacOptions ++= Seq(
  "-Xfatal-warnings",
  "-deprecation"
)

// Different options for Compile configuration  
Compile / scalacOptions ++= Seq(
  "-Werror",
  "-Wunused:all"
)

Scala 2 vs Scala 3

Key differences when configuring:

Feature	Scala 2	Scala 3
Binary Version	2.12, 2.13	3
Compiler Bridge	scala2-sbt-bridge	scala3-sbt-bridge
Warning Options	-Ywarn-*	-W*
Language Features	-language:*	Built-in or -language:*

sbt automatically handles different compiler bridges for Scala 2 and Scala 3, so you don’t need to configure this manually.

Dynamic Scala Versions

You can use dynamic version strings that sbt resolves:

build.sbt

scalaVersion := "3-latest.candidate"
// Resolves to the latest Scala 3 candidate release

The scalaDynVersion task performs this resolution.

Best Practices

1. Pin your Scala version

   Always specify an exact scalaVersion in your build.sbt for reproducible builds.

2. Use crossScalaVersions for libraries

   If you’re building a library, support multiple Scala versions using crossScalaVersions.

3. Keep compiler options consistent

   Use the same compiler options across configurations unless you have a specific reason not to.

4. Test with -Xfatal-warnings

   Consider making warnings fatal in CI to catch issues early.