Text Editors

Latest Metals server versions

To find out how to set the version in your editor please check out the editor specific sections.

Version	Published
1.4.1	15 Nov 2024 13:46
1.4.1+21-d1fce175-SNAPSHOT	19 Nov 2024 10:10

Snapshot releases are not guaranteed to work.

Editor support

Metals works with the following text editors with varying degree of functionality.

	Visual Studio Code	Vim	Sublime Text	Emacs	Helix
Installation	Single click	Single click	Single click	Single click	Manual
Build import	✅	✅	✅	✅	✅
Diagnostics	✅	✅	✅	✅	✅
Goto definition	✅	✅	✅	✅	✅
Goto type definition	✅	✅	✅	✅	✅
Completions	✅	✅*	✅	✅	✅
Hover	✅	✅	✅	✅	✅
Hover for selection	✅	✅	✅	❌	✅
Parameter hints	✅	✅	✅	✅	✅
Find references	✅	✅	✅	✅	✅
Run/Debug	✅			✅	❌
Find implementations	✅	✅	✅	✅	✅
Rename symbol	✅	✅	✅	✅	✅
Code actions	✅	✅	✅	✅	✅
Worksheets	✅	✅	✅	✅	✅
Document symbols	✅	Flat	Flat	✅	Flat
Workspace symbols	✅	✅	✅	✅	✅
Formatting	✅	✅	✅	✅	✅
Folding	✅	✅		✅	❌
Highlight	✅	✅	✅	✅	✅
Metals Extensions	✅	✅	Status bar, Input box, Decoration protocol, Did focus	✅	❌
Organize imports	✅	✅	✅	✅	❌
Implicit decorations	✅	Shown in hover	✅	✅	✅
Source file analyzer	✅	✅	✅	✅	❌
Find text in dependency JAR files	✅	✅	✅	❌	✅
Run scalafix rules	✅	✅	✅	✅	❌

Installation

Single click: Metals is easy to install and requires minimal configuration out-of-the-box.

Few steps: installing Metals requires a few custom steps and minimal configuration to work.

You can find instructions on how to install Metals for your editor on its specific page.

Build import

✅: it is possible to import a build such as an sbt project directly from the editor.

Requires browser: importing a build requires additional steps in a web browser using a localhost server. It is not possible to import a build within the editor.

Diagnostics

✅: Diagnostics are correctly published on compile.

Compile errors are reported as red squiggles in the editor. Compilation is triggered on file save for the build target (project/module) containing the focused text file.

Known limitations

• Slow feedback for type errors. Syntax errors are published as you type but type errors are handled by the build tool, meaning diagnostics may take a while to publish for large projects.

Goto definition

Navigate to symbol definitions for project sources and Scala/Java library dependencies.

Symbols are resolved according to the last successful compilation in the build tool and navigation continues to work despite syntax errors in the open unsaved buffer.

Known limitations

• Navigation does not work for buffers that do not tokenize, for example due to unclosed string literals.
• scalameta/scalameta#1802 reflective invocations (methods calls on structural types) do not resolve to a definition.

Completions

Use code completions to explore APIs, implement interfaces, generate exhaustive pattern matches and more.

• Auto-import: imports are inserted at the bottom of the global import list. Imports still need to be sorted and grouped manually, we are exploring ways to automate this workflow in the future.
• Override def: implement methods from the super class.
• Exhaustive match: generate an exhaustive pattern match for sealed types.
• String interpolator: automatically convert string literals into string interpolators.
• Filename: complete classnames based on the enclosing file.
• Documentation: read the docstring for method symbols by pressing ctrl+space in VS Code.

Known limitations

• completion results don't include symbols that have just been typed in separate files without a successful compilation in the build tool.

Hover (aka. type at point)

See the expression type and symbol signature under the cursor.

• Expression type: shows the non-generic type of the highlighted expression.
• Symbol signature: shows the generic signature of symbol under the cursor along with its docstring, if available.

Signature help (aka. parameter hints)

View a method signature and method overloads as you fill in the arguments.

Find references

Find symbol references in project sources. References include implicits, inferred .apply, desugared .flatMap from for comprehensions and other symbols that may not be explicitly written in source, making it possible to discover usages of difficult-to-grep symbols. The Metals navigation index is low-overhead and should only require a few megabytes of memory even for large projects.

Known limitations

• References to overridden methods are not included in the results. For example, if you run "find references" on the method Dog.name() then it won't include references to the super method Animal.name().

Worksheets

✅: Worksheets work via the Decoration protocol and are added as a non-editable side decoration.

Comments: Worksheets work via workspace/applyEdit by adding comments to the source code and support hover to show larger output. You can find more information about worksheets under the editor specific worksheet section. For example, here for VS Code.

By default there is a 30 second timeout on worksheet evaluation, this setting can be overridden by -Dmetals.worksheet-timeout=<number of seconds> server property.

Document symbols

✅: Document symbols are displayed in a hierarchical outline.

Flat: Document symbols are displayed in a flat outline.

Workspace symbols

Fuzzy search a symbol in the workspace of library dependencies by its name.

• All-lowercase queries are treated as case-insensitive searches.
• Queries ending with a dot . list nested symbols.
• Queries containing a semicolon ; search library dependencies.

Formatting

Metals uses Scalafmt to respond to formatting requests from the editor, according to the configuration defined in .scalafmt.conf.

Learn how to configure Scalafmt at https://scalameta.org/scalafmt/docs/configuration.html.

Code folding

Fold ranges such as large multi-line expressions, import groups and comments.

Document highlight

Highlight references to the same symbol in the open file.

Package explorer

Browse packages, classes and methods in the workspace and library dependencies using the Metals sidebar. This feature is only implemented in VS Code.

Test Explorer

Test Explorer is a feature that allows editors to display tests as a separate tree representation of tests. Although it was implemented in order to use Visual Studio Code's Testing API. The Test Explorer API is editor agnostic and can be used by other editors than just VS Code.

Work on the Test Explorer is still in progress and the feature has some known limitations:

• Test Explorer is able to discover single test cases only for JUnit4 test classes. Support for other test frameworks is being worked on.
• detecting suites in cross scala-version projects is inconsistent, see this issue.
• there is no support for JS and Native platforms. For any changes subscribe to the related feature request.

You can find more information about Test Explorer under the VS Code specific section.

Running Tests

Both run and debug under the hood use BSP's debug request. More information about it can be found at Bloop DAP diagram or BSP specification website.

Metals Extensions

Status bar: Editor client implements the metals/status notification.

Decoration protocol: Editor client implements the Decoration Protocol.

Tree view: Editor client implements the Tree View Protocol.

Did focus: Editor client implements the metals/didFocusTextDocument notification.

Input box: Editor client implements the metals/inputBox request.

Quick pick: Editor client implements the metals/quickPick request.

Window state: Editor client implements the metals/windowStateDidChange notification.

✅: Editor implements all Metals extension endpoints.

The Metals language server supports custom extensions that are not part of the Language Server Protocol (LSP). These extensions are not necessary for Metals to function but they improve the user experience. To learn more about Metals extensions, see integrating a new editor.

Implicit decorations

✅: Additional information inferred from the code can be show within the code using virtual text.

Shown in hover: Additional information inferred from the code can be show when hovering over a specific line. That hover only shows the additional symbols on the current line.

Additional file types

Not all features are supported in all possible scenarios, especially when it comes to non-standard Scala files like Ammonite scripts, worksheets or sbt scripts.

	sbt scripts	Worksheets	Ammonite scripts*	Standalone Scala files
Diagnostics	✅*	✅	✅	✅*
Goto definition	✅	✅	✅	✅
Completions	✅	✅	✅	✅
Hover	✅	✅	✅	✅
Parameter hints	✅	✅	✅	✅
Find references	✅	✅	✅	✅
Run/Debug
Find implementations	✅		✅	✅
Rename symbol	✅	✅	✅	✅
Code actions	✅	✅	✅	✅
Document symbols	✅	✅	✅	✅
Workspace symbols	✅	All symbols are local	✅	✅
Formatting	✅	✅	✅	✅
Folding	✅	✅	✅	✅
Highlight	✅	✅	✅	✅
Organize imports
Implicit decorations	✅		✅	✅
Decode file (cfr, semanticdb, tasty, javap)

* Note that there are some specific Ammonite features that aren't supported like multi-stage scripts. Currently Ammonite support is also limited to Scala 2.

* Diagnostics for sbt script and standalone Scala files will only show parsing errors, but not diagnostics coming from the compiler.