Skip to main content

Visual Studio Code

Goto Definition


Java 8, 11, 17 provided by OpenJDK or Oracle. Eclipse OpenJ9 is not supported, please make sure the JAVA_HOME environment variable points to a valid Java 8, 11 or 17 installation.

macOS, Linux or Windows. Metals is developed on many operating systems and every PR is tested on Ubuntu, Windows and MacOS.

Scala 2.13, 2.12, 2.11 and Scala 3. Metals supports these Scala versions:

  • Scala 2.13: 2.13.6, 2.13.5, 2.13.4, 2.13.3, 2.13.2, 2.13.1, 2.13.0

  • Scala 2.12: 2.12.15, 2.12.14, 2.12.13, 2.12.12, 2.12.11, 2.12.10, 2.12.9, 2.12.8

  • Scala 2.11: 2.11.12

  • Scala 3: 3.1.0-RC2, 3.0.2, 3.0.1, 3.0.0

Note that 2.11.x support is deprecated and it will be removed in future releases. It's recommended to upgrade to Scala 2.12 or Scala 2.13


Install the Metals extension from the Marketplace.

Install Metals extension

Make sure to disable the extensions Scala Language Server and Scala (sbt) if they are installed. The Dotty Language Server does not need to be disabled because the Metals and Dotty extensions don't conflict with each other. However, if you want to work on Scala 3 code in a workspace that was previously opened with Dotty Language Server you need to first remove .dotty-ide-artifact before opening the workspace with Metals.

Next, open a directory containing your Scala code. The extension activates when the main directory contains build.sbt or file, a Scala file is opened, which includes *.sbt, *.scala and *.sc file, or a standard Scala directory structure src/main/scala is detected.

Importing a build#

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

Import build

  • "Not now" disables this prompt for 2 minutes.
  • "Don't show again" disables this prompt forever, use rm -rf .metals/ to re-enable the prompt.
  • Use tail -f .metals/metals.log to watch the build import progress.
  • Behind the scenes, Metals uses Bloop to import sbt builds, but you don't need Bloop installed on your machine to run this step.

Once the import step completes, compilation starts for your open *.scala files.

Once the sources have compiled successfully, you can navigate the codebase with goto definition.

Custom sbt launcher#

By default, Metals runs an embedded sbt-launch.jar launcher that respects .sbtopts and .jvmopts. However, the environment variables SBT_OPTS and JAVA_OPTS are not respected.

Update the "Sbt Script" setting to use a custom sbt script instead of the default Metals launcher if you need further customizations like reading environment variables.

Sbt Launcher

Speeding up import#

The "Import build" step can take a long time, especially the first time you run it in a new build. The exact time depends on the complexity of the build and if library dependencies need to be downloaded. For example, this step can take everything from 10 seconds in small cached builds up to 10-15 minutes in large uncached builds.

Consult the Bloop documentation to learn how to speed up build import.

Importing changes#

When you change build.sbt or sources under project/, you will be prompted to re-import the build.

Import sbt changes

Manually trigger build import#

To manually trigger a build import, execute the "Import build" command through the command palette (Cmd + Shift + P).

Import build command

Run doctor#

Execute the "Run Doctor" through the command palette to troubleshoot potential configuration problems in your workspace.

Run doctor command

Configure Java version#

The VS Code plugin uses by default the JAVA_HOME environment variable (via locate-java-home) to locate the java executable. To override the default Java home location, update the "Java Home" variable in the settings menu.

Java Home setting

If this setting is defined, the VS Code plugin uses the custom path instead of the JAVA_HOME environment variable.


To globally configure $JAVA_HOME for all GUI applications, see this Stackoverflow answer.

If you prefer to manually configure Java home through VS Code, run the following command to copy the Java 8 home path.

/usr/libexec/java_home -v 1.8 | pbcopy

Custom artifact repositories (Maven or Ivy resolvers)#

Use the 'Custom Repositories' setting for the Metals VS Code extension to tell Coursier to try to download Metals artifacts from your private artifact repository.

Use .jvmopts to set sbt options ( for sbt bloopInstall which resolves library dependencies. You can also provide a custom sbt script (see 'Custom sbt launcher').

HTTP proxy#

Metals uses Coursier to download artifacts from Maven Central. To use Metals behind an HTTP proxy, configure the system properties -Dhttps.proxyHost=… -Dhttps.proxyPort=… in one of the following locations:

  • .jvmopts file in the workspace directory.
  • JAVA_OPTS environment variable, make sure to start code from your terminal when using this option since environment variables don't always propagate correctly when opening VS Code as a GUI application outside a terminal.
  • "Server Properties" setting for the Metals VS Code extension, which can be configured per-workspace or per-user.

Using latest Metals SNAPSHOT#

Update the "Server Version" setting to try out the latest pending Metals features.

0.10.716 Sep 2021 16:28
0.10.7+17-f589e8b6-SNAPSHOT18 Sep 2021 10:35
Run the "Reload Window" command after updating the setting for the new version to take effect.

Files and Directories to include in your Gitignore#

The Metals server places logs and other files in the .metals directory. The Bloop compile server places logs and compilation artifacts in the .bloop directory. The Bloop plugin that generates Bloop configuration is added in the metals.sbt file, which is added at project/metals.sbt as well as further project directories depending on how deep *.sbt files need to be supported. To support each *.sbt file Metals needs to create an additional file at ./project/project/metals.sbt relative to the sbt file. Working with Ammonite scripts will place compiled scripts into the .ammonite directory. It's recommended to exclude these directories and files from version control systems like git.

# ~/.gitignore

Show document symbols#

Run the "Explorer: Focus on Outline View" command to open the symbol outline for the current file in the sidebar.

Document Symbols Outline

Run the "Open Symbol in File" command to search for a symbol in the current file without opening the sidebar.

Document Symbols Command

As you type, the symbol outline is also visible at the top of the file. Document Symbols Outline

Go to parent code lenses#

Metals has the ability to display code lenses that, when invoked, will go to the parent class that contains the definition of the method or symbol. Unfortunately, it might cause some lag in larger code bases, which is why it is not enabled currently by default.

To enable the feature you need to modify the setting metals.superMethodLensesEnabled to true.

Even without using the code lenses it's still possible to navigate the method hierarchy using two commands:

  • Metals: Go to super method - immediately goes to the parent of the method the cursor is pointing to

  • Metals: Reveal super method hierachy - displays the full method hierachy and enables to move to any parent, it is best used with the Metals Quick Pick extension.

You can also bind those commands to a shortcut.

Create new project from template#

It is possible using Metals to easily setup a new project using the exiting giter8 templates. This is an equivalent to the sbt new command, which uses the same mechanism. There is a great number of templates already available and it should be easy to find something for yourself. To start the setup you can use the Metals: New Scala project command, which works as following:

  1. Choose the template and then:

    1. Use the proposed templates.
    2. Choose "Discover more" and then choose from the list downloaded from the Giter8 wiki page.
    3. Input a custom Github repository following the organization/repo schema.
  2. Navigate to the parent directory that you want to create your new project in.

  3. Choose the name or accept the default one.

  4. Choose whether to open a new window for the created project or use the existing one.

The same command will be invoked when clicking the "New Scala Project" button in the Metals view.

If you feel like a template should be included in the default displayed ones do not hesitate to create a PR or file an issue.

Running and debugging your code#

Metals supports running and debugging tests and main methods via the Debug Adapter Protocol. The protocol is used to communicate between the editor and debugger, which means that applications can be run the same as for any other language in the natively supported Run view. When using Metals the debugger itself is Bloop, which is also responsible for starting the actual process.

Users can begin the debugging session in two ways:

via code lenses#


For each main or test class Metals shows two code lenses run | debug or test | test debug, which show up above the definition as a kind of virtual text. Clicking run or test will start running the main class or test without stopping at any breakpoints, while clicking debug or test debug will pause once any of them are hit. It's not possible to add any arguments or java properties when running using this method.

via a launch.json configuration#

Visual Studio Code uses .vscode/launch.json to store user defined configurations, which can be run using:

  • The Run -> Start Debugging menu item or workbench.action.debug.start shortcut.
  • The Run -> Run Without Debugging menu item or shortcut.

If a user doesn't have anything yet saved, a configuration wizard will pop up to guide them. In the end users should end up with something like this:

"version": "0.2.0",
"configurations": [
// Main class configuration
"type": "scala",
"request": "launch",
// configuration name visible for the user
"name": "Launch Main",
// full name of the class to run
"mainClass": "com.example.Main",
// optional arguments for the main class
"args": [],
// optional jvm properties to use
"jvmOptions": []
// Test class configuration
"type": "scala",
"request": "launch",
// configuration name visible for the user
"name": "Launch Test",
// full name of the class to run
"testClass": "com.example.Test"

You can also add an optional build target name, which is needed in case there are more than one class with the same name or when launching a class from outside the project. Inside "configurations": add the key buildTarget with your target name, e.g. root:

"buildTarget": "root"

The build target name corresponds to your project name. For example in sbt for lazy val interfaces = project the name of the build target will be interfaces for sources and interfaces-test for tests. To make sure you have the correct target names please run the command Metals: Run Doctor.

Multiple configurations can be stored in that file and can be chosen either manually in the Run view or can be picked by invoking a shortcut defined under workbench.action.debug.selectandstart.

via Metals' commands#

You can also use commands that can be easily bound to shortcuts:

  • - Run main class in the current file.
  • metals.test-current-file - Run test class in the current file
  • metals.test-current-target - Run all tests in the current project.

To assign shortcuts just go to the Keyboard Shortcuts page (File -> Preferences -> Keyboard Shortcuts) and search for a command, click on it and use you preffered shortcut.

On type formatting for multiline string formatting#


To properly support adding | in multiline strings we are using the onTypeFormatting method. The functionality is enabled by default, but you can disable/enable onTypeFormatting inside Visual Studio Code settings by checking Editor: Format On Type:


Formatting on paste for multiline strings#

Whenever text is paste into a multiline string with | it will be properly formatted by Metals:


This feature is enabled by default. If you need to disable/enable formatting on paste in Visual Studio Code you can check the Editor: Format On Paste setting:



Worksheets are a great way to explore an api, try out an idea, or code up an example and quickly see the evaluated expression or result. Behind the scenes worksheets are powered by the great work done in mdoc.

Getting started with Worksheets#

To get started with a worksheet you can either use the command and select Worksheet or create a file called * This format is important since this is what tells Metals that it's meant to be treated as a worksheet and not just a Scala script. Where you create the script also matters. If you'd like to use classes and values from your project, you need to make sure the worksheet is created inside of your src directory. You can still create a worksheet in other places, but you will only have access to the standard library and your dependencies.


After saving you'll see the result of the expression as a decoration at the end of the line. You may not see the full result for example if it's too long, so you are also able to hover on the decoration to expand the decoration.

Keep in mind that you don't need to wrap your code in an object. In worksheets everything can be evaluated at the top level.

Using dependencies in worksheets#

You are able to include an external dependency in your worksheet by including it in one of the following two ways.

// $dep.`organisation`::artifact:version` style
import $dep.`com.lihaoyi::scalatags:0.7.0`
// $ivy.`organisation::artifact:version` style
import $ivy.`com.lihaoyi::scalatags:0.7.0`

:: is the same as %% in sbt, which will append the current Scala binary version to the artifact name.

You can also import scalac options in a special $scalac import like below:

import $scalac.`-Ywarn-unused`

Searching a symbol in the workspace#

Metals provides an alternative command to the native "Go to symbol in workspace..." command, in order to work around some VS Code limitations (see this issue for more context) and provide richer search capabilities.

You can invoke this command from the command palette (look for "Metals: Search symbol in workspace"). Optionally you can also bind this command to a shorcut. For example, if you want to replace the native command with the Metals one you can configure this shortcut:

"key": "ctrl+t", // or "cmd+t" if you're on macOS
"command": "metals.symbol-search",
"when": "editorLangId == scala"

Coming from IntelliJ#

Install the IntelliJ IDEA Keybindings extension to use default IntelliJ shortcuts with VS Code.

IntelliJVS Code
Go to classGo to symbol in workspace
Parameter infoTrigger parameter hints
Basic completionTrigger suggest
Type infoShow hover
Extend SelectionExpand selection

GitHub Codespaces and support#