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 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.
Version | Published |
---|---|
1.4.0 | 24 Oct 2024 09:53 |
1.4.0+34-caf518ed-SNAPSHOT | 11 Nov 2024 09:54 |
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.
- Most easily is to just use Coursier to do a
cs install metals
. - 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.0 -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.0 -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.