Skip to main content

Vim

nvim-metals demo

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 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 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.11: 2.11.12

  • Scala 2.12: 2.12.17, 2.12.18, 2.12.19, 2.12.20

  • Scala 2.13: 2.13.12, 2.13.13, 2.13.14, 2.13.15

  • Scala 3: 3.3.1, 3.3.3

Scala 3 versions from 3.3.4 are automatically supported by Metals.

Any older Scala versions will no longer get bugfixes, but should still work properly with newest Metals.

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 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.

VersionPublished
1.4.216 Dec 2024 14:05
1.4.2+29-82907609-SNAPSHOT20 Dec 2024 15:31

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:

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
coursier bootstrap org.scalameta:metals_2.13:1.4.2 -o metals -f

(optional) It's recommended to enable JVM string de-duplication and provide a generous stack size and memory options.

coursier bootstrap \
  --java-opt -XX:+UseG1GC \
  --java-opt -XX:+UseStringDeduplication  \
  --java-opt -Xss4m \
  --java-opt -Xms100m \
  org.scalameta:metals_2.13:1.4.2 -o metals -f

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.

Running scalafix rules​

Scalafix allows users to specify some refactoring and linting rules that can be applied to your codebase. Please checkout the scalafix website for more information.

Since Metals v0.11.7 it's now possible to run scalafix rules using a special command metals.scalafix-run. This should run all the rules defined in your .scalafix.conf file. All built-in rules and the community hygiene ones can be run without any additional settings. However, for all the other rules users need to add an additional dependency in the metals.scalafixRulesDependencies user setting. Those rules need to be in form of strings such as com.github.liancheng::organize-imports:0.6.0, which follows the same convention as coursier dependencies.

A sample scalafix configuration can be seen below:

rules = [
  OrganizeImports,
  ExplicitResultTypes,
  RemoveUnused
]

RemoveUnused.imports = false

OrganizeImports.groupedImports = Explode
OrganizeImports.expandRelative = true
OrganizeImports.removeUnused = true
OrganizeImports.groups = [
  "re:javax?\."
  "scala."
  "scala.meta."
  "*"
]

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.