Metals is still in early development so you may run into rough edges. 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 or 11 provided by OpenJDK or Oracle. Eclipse OpenJ9 is not supported,
please make sure the
JAVA_HOME environment variable points to a valid Java 8
or 11 installation.
macOS, Linux or Windows. Metals is developed on macOS and every PR is tested
Scala 2.13, 2.12 and 2.11. Metals supports these Scala versions 2.13.0,
2.13.1, 2.12.8, 2.12.9, 2.12.10, 2.12.7 and 2.11.12. 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.
Next, open a directory containing a
build.sbt file. The extension activates
*.sbt file is opened.
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
find-java-home) to locate the
java executable. Metals only works with Java 8 so this executable cannot point
to another version such as Java 11.
To override the default Java home location, update the "Java Home" variable to
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.
The Metals server places logs and other files in the
.metals/ directory. The
Bloop compile server places logs and compilation artifacts in the
directory. It's recommended to ignore these directories from version control
systems like git.
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.
Enable on type formatting for multiline string formatting
To properly support adding
| in multiline strings we are using the
onTypeFormatting method. To enable the functionality you need to enable
onTypeFormatting inside Visual Studio Code.
This needs to be done in settings by checking
Editor: Format On Type:
Enable formatting on paste for multiline strings
Whenever text is paste into a multiline string with
| it will be properly
formatted by Metals:
To enable this feature you need to enable formatting on paste in Visual Studio
Code by checking
Editor: Format On PAste:
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