The following table shows the status of various features.
||Works with sbt, Gradle, Maven, Mill and Bloop.
||Syntax errors as you type and type errors on file save.
|Hover (type at point)
||Works for project sources and Java/Scala library dependencies.
||Searches workspace sources and library dependencies. All-lowercase queries are case-insensitive.
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:
2.13.6, 2.13.5, 2.13.4, 2.13.3, 2.13.2, 2.13.1, 2.13.0
2.12.15, 2.12.14, 2.12.13, 2.12.12, 2.12.11, 2.12.10, 2.12.9, 2.12.8
3.1.1-RC1, 3.1.0, 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
Make sure to disable the extensions
Scala Language Server
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
.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.sc file, a Scala file is
opened, which includes
*.sc file, or a standard Scala
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.
- "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.
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
Once the sources have compiled successfully, you can navigate the codebase with
Custom sbt launcher
By default, Metals runs an embedded
sbt-launch.jar launcher that respects
.jvmopts. However, the environment variables
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
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
to learn how to speed up build import.
When you change
build.sbt or sources under
project/, you will be prompted to
re-import the build.
Manually trigger build import
To manually trigger a build import, execute the "Import build" command through
the command palette (
Cmd + Shift + P).
Execute the "Run Doctor" through the command palette to troubleshoot potential
configuration problems in your workspace.
Configure Java version
The VS Code plugin uses by default the
JAVA_HOME environment variable (via
locate-java-home) to locate
java executable. To override the default Java home location, update the
"Java Home" variable in the settings menu.
If this setting is defined, the VS Code plugin uses the custom path instead of
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.
.jvmopts to set sbt options
sbt bloopInstall which resolves library dependencies. You can also provide a
custom sbt script (see 'Custom sbt launcher').
Metals uses Coursier to download
artifacts from Maven Central. To use Metals behind an HTTP proxy, configure the
-Dhttps.proxyHost=… -Dhttps.proxyPort=… in one of the
.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.
Update the "Server Version" setting to try out the latest pending Metals
to find the latest SNAPSHOT version.
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
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
Show document symbols
Run the "Explorer: Focus on Outline View" command to open the symbol outline for
the current file in the sidebar.
Run the "Open Symbol in File" command to search for a symbol in the current file
without opening the sidebar.
As you type, the symbol outline is also visible at the top of the file.
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
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
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
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:
Choose the template and then:
- Use the proposed templates.
- Choose "Discover more" and then choose from the list downloaded from the
Giter8 wiki page.
- Input a custom Github repository following the
Navigate to the parent directory that you want to create your new project in.
Choose the name or accept the default one.
Choose whether to open a new window for the created project or use the
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
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
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
test will start running the main class or test without
stopping at any breakpoints, while clicking
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.
Visual Studio Code uses
.vscode/launch.json to store user defined
configurations, which can be run using:
Run -> Start Debugging menu item or
Run -> Run Without Debugging menu item or
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:
// Main class configuration
// configuration name visible for the user
"name": "Launch Main",
// full name of the class to run
// optional arguments for the main class
// optional jvm properties to use
// Test class configuration
// configuration name visible for the user
"name": "Launch Test",
// full name of the class to run
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
your target name, e.g.
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
You can also use commands that can be easily bound to shortcuts:
metals.run-current-file - 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 (
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
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
Getting started with Worksheets
To get started with a worksheet you can either use the
command and select Worksheet or create a file called
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
// $ivy.`organisation::artifact:version` style
:: 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:
Coming from IntelliJ
IntelliJ IDEA Keybindings
extension to use default IntelliJ shortcuts with VS Code.
|Go to class
||Go to symbol in workspace
||Trigger parameter hints
GitHub Codespaces and GitHub.dev support