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 following packages:
sublimelsp/LSP: Language Server Protocol support for Sublime Text.
Command Palette (Cmd + Shift + P) > Install package > LSP
scalameta/metals-sublime: For automatic installation of metals and custom commands.
Command Palette (Cmd + Shift + P) > Install package > LSP-metals
Finally restart sublime text.
Next, open "Preferences > Key Binding" and register
F12 to trigger goto
Open Sublime in the base directory of your Scala project and it will then prompt you to import the build as long as you're using one of the supported build tools. Click "Import build" to start the installation step.
This starts the Metal language server but no functionality will work yet because the build has not been imported.
This step can take a long time, especially the first time you run it in a new workspace. The exact time depends on the complexity of the build and if the library dependencies are cached or need to be downloaded. For example, this step can take anywhere from 10 seconds in small cached builds up to 10-15 minutes in large un-cached builds.
For more detailed information about what is happening behind the scenes during
sbt bloopInstall run
lsp toggle server panel in the command palette. You can optionally add key binding for this command.
Once the import step completes, compilation starts for your open
files. Once the sources have compiled successfully, you can navigate the the
sources with "Goto definition" by pressing
The default key binding is
shift+F12. If you use vim-bindings, you need to be
You can search for symbols in your dependency source using the command palette.
You can optionally register a key binding for the command.
This paragraph contains a few tips & trick that can improve your daily productivity with Metals.
If you prefer to only enable Metals completions (without mixing them with the default ones from Sublime) set the following setting in the "Preferences > Preferences: LSP Settings":
Also, if you prefer to show symbol references in Sublime's quick panel instead of the bottom panel set following setting in the "Preferences > Preferences: LSP Settings":
You can set a few optional key mappings for enable useful action shortcuts and perform some tweaks for the completion popup.
Open "Preferences > Key Binding" and register
ctrl+alt+l to trigger formating document.
This an optional step if you want to have a shortcut for looking up symbols in the workspace. Open "Preferences > Key Binding" and add:
Metals can complete symbols from your workspace scope and automatically import them. By default, however, if you hit "Enter" to select a completion, the LSP client will complete the class without importing it, but you can easy remap to use also "Enter" key. Open "Preferences > Key Binding" and add:
Update the "server_version" setting to try out the latest pending Metals
features by accessing
Preferences > Package Settings > LSP > Servers > LSP-metals
|0.10.7||16 Sep 2021 16:28|
|0.10.7+17-f589e8b6-SNAPSHOT||18 Sep 2021 10:35|
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
It's recommended to exclude these directories and files
from version control systems like git.
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.
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
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 comment as 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 comment to expand.
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.
You are able to include an external dependency in your worksheet by including it in one of the following two ways.
:: 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: