Vim

While Metals works with most LSP clients for Vim and Neovim, we recommend using the dedicated Neovim plugin to get the best Metals support. Metals has many specific commands and LSP extensions that won't be available when not using the extension.

Requirements

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.8, 2.13.7, 2.13.6, 2.13.5, 2.13.4, 2.13.3, 2.13.2, 2.13.1

• Scala 2.12: 2.12.16, 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.2.0-RC1, 3.1.3, 3.1.2, 3.1.1, 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

nvim-metals

nvim-metals Is the the dedicated Metals extension for the built-in LSP support in Neovim.

To get started with installation please see the nvim-metals prerequisites and installation steps.

Version	Published
0.11.6	03 Jun 2022 11:19
0.11.6+162-a9ee0ee8-SNAPSHOT	01 Jul 2022 14:02

Keep in mind that by default Neovim doesn't have default mappings for the functionality you'll want like, hovers, goto definition, method signatures, etc. You can find a full example configuration of these in the example configuration.

For a guide on all the available features in nvim-metals, refer to the features list.

Vim alternatives

There are multiple Vim alternatives if you're not a Neovim user. Metals did have a Metals-specific plugin that worked with Vim, coc-metals, but it doesn't work with the newest versions of Metals and is currently deprecated and unmaintained.

Using an alternative LSP Client

There are multiple other LSP clients that work with Vim. Here are a few:

• natebosch/vim-lsc: simple installation and written in Vimscript.
• vim-lsp: simple installation and written in Vimscript.
• yegappan/lsp: Very new and targeting Vim9.

Keep in mind that they have varying levels of LSP support, don't support Metals specific commands (like build import), or Metals specific LSP extensions (like tree view), and you need to manage the Metals installation yourself.

There are two ways to install Metals yourself in order to work with an alternative client.

1. Most easily is to just use Coursier to do a cs install metals.
2. Generating a Metals binary yourself.

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
.metals/
.bloop/
.ammonite/
metals.sbt

Next, build a metals-vim binary for the latest Metals release using the Coursier command-line interface.

Version	Published	Resolver
0.11.6	03 Jun 2022 11:19	-r sonatype:releases
0.11.6+162-a9ee0ee8-SNAPSHOT	01 Jul 2022 14:02	-r sonatype:snapshots

# Make sure to use coursier v1.1.0-M9 or newer.
curl -L -o coursier https://git.io/coursier-cli
chmod +x coursier
./coursier bootstrap \
  --java-opt -Xss4m \
  --java-opt -Xms100m \
  --java-opt -Dmetals.client=vim-lsc \
  org.scalameta:metals_2.13:0.11.6 \
  -r bintray:scalacenter/releases \
  -r sonatype:snapshots \
  -o /usr/local/bin/metals-vim -f

Make sure the generated metals-vim binary is available on your $PATH.

You can check version of your binary by executing metals-vim -version.

Configure the system properties -Dhttps.proxyHost=… -Dhttps.proxyPort=… if you are behind an HTTP proxy.

The -Dmetals.client=vim-lsc flag is there just as a helper to match your potential client. So make sure it matches your client name. This line isn't mandatory though as your client should be able to fully be configured via InitializationOptions. You can read more about his here.

Getting help

There is an active community using Vim and Metals. Apart from creating an issue or starting a discussion for nvim-metals users, you can also ask questions in our #vim-users Discord Channel or Matrix Bridge.