sbt · Metals

sbt is most commonly used build tool in the Scala community and works with Metals out-of-the-box.

Automatic installation

The first time you open Metals in a new workspace it prompts you to import the build. Select "Import build" to start automatic installation.

Import build

Install without Bloop

Automatic build import for sbt happens through Bloop, a compile server for Scala. Bloop implements the Build Server Protocol (BSP) that Metals uses to learn the directory structure of your project and its library dependencies. sbt does not implement BSP so Metals is not able to import sbt builds without Bloop.

Manual installation

It's recommended to use automatic installation over manual installation since manual installation requires several independent steps that makes it harder to stay up-to-date with the latest Metals version.

Instead of using automatic build import, you can manually install sbt-bloop and generate the Bloop JSON files directly from your sbt shell. This approach may speed up build import by avoiding Metals from starting sbt in a separate process.

For latest SNAPSHOT

First, install the Bloop plugin globally or inside your project directory:

// One of:
//   ~/.sbt/0.13/plugins/plugins.sbt
//   ~/.sbt/1.0/plugins/plugins.sbt
resolvers += Resolver.sonatypeRepo("snapshots")
addSbtPlugin("ch.epfl.scala" % "sbt-bloop" % "1.3.3")

Next, run:

sbt "set bloopExportJarClassifiers := Some(Set(\"source\"))" bloopInstall

to generate the Bloop JSON configuration files. You can also set bloopExportJarClassifiers setting inside your main build.sbt file, but using the above command will do it automatically for you in the current sbt session.

Finally, once bloopInstall is finished, execute the "Connect to build server" command (id: build.connect) command to tell Metals to establish a connections with the Bloop build server.

For versions up to 0.7.6

First, install the Bloop and Metals plugins globally

// One of:
//   ~/.sbt/0.13/plugins/plugins.sbt
//   ~/.sbt/1.0/plugins/plugins.sbt
resolvers += Resolver.sonatypeRepo("snapshots")
addSbtPlugin("org.scalameta" % "sbt-metals" % "0.7.7-SNAPSHOT")
addSbtPlugin("ch.epfl.scala" % "sbt-bloop" % "1.3.3")

Next, run sbt metalsEnable bloopInstall to generate the Bloop JSON configuration files.

Finally, once bloopInstall is finished, execute the "Connect to build server" command (id: build.connect) command to tell Metals to establish a connections with the Bloop build server.

For more information about sbt-bloop, consult the Bloop website.

Permanent metalsEnable

If you use manual installation, you can avoid running the metalsEnable command in every sbt session with the following steps.

First, update the global Bloop settings to download sources of external libraries.

// One of:
//   ~/.sbt/0.13/build.sbt
//   ~/.sbt/1.0/build.sbt
bloopExportJarClassifiers.in(Global) := Some(Set("sources"))

Next, update your build settings to use the semanticdb-scalac compiler plugin.

// build.sbt
 lazy val myproject = project.settings(
+  scalaVersion := "2.12.10", // or 2.11.12, other versions are not supported.
+  addCompilerPlugin(MetalsPlugin.semanticdbModule), // enable SemanticDB
+  scalacOptions += "-Yrangepos" // required by SemanticDB
 )

Now, you can run sbt bloopInstall without the metalsEnable step.

Pro tip: With semanticdb-scalac enabled in your sbt build can also use Scalafix.

Customizing build import

Consult the Bloop docs for customizing build import for sbt: https://scalacenter.github.io/bloop/docs/build-tools/sbt

Enable IntegrationTest and other custom configurations
Speed up build import
Enable sbt project references (source dependencies)
Export main class

Troubleshooting

Before reporting an issue, check if your problem is solved with one of the following tips.

Waiting for lock on .ivy2/.sbt.ivy.lock

Metals run sbt in a separate process and this error happens where there are two sbt processes resolving dependencies at the same time.

Not valid key: metalsEnable

This error might indicate that you have an old version of sbt-metals installed in your project.

[error] Not a valid key: metalsEnable (similar: scalafixEnabled)
[error] metalsEnable
[error]             ^

Try to remove any usage of sbt-metals in your build.