Metals works in Emacs thanks to the
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
To use Metals in Emacs, place this snippet in your Emacs configuration (for example .emacs.d/init.el) to load
lsp-mode along with its dependencies:
You may need to disable other packages like
ensimeor sbt server to prevent conflicts with Metals.
Next you have to install metals server. Emacs can do it for you when
is enabled in a scala buffer or via
lsp-install-server command. Also you can
do it manually executing
coursier install metals and configuring
The first time you open Metals in a new workspace it prompts you to import the build.
Type "Import build" or press
Tab and select "Import build" to start the installation step.
- "Not now" disables this prompt for 2 minutes.
- "Don't show again" disables this prompt forever, use
rm -rf .metals/to re-enable the prompt.
tail -f .metals/metals.logto watch the build import progress.
- Behind the scenes, Metals uses Bloop to import sbt builds, but you don't need Bloop installed on your machine to run this step.
Once the import step completes, compilation starts for your open
Once the sources have compiled successfully, you can navigate the codebase with goto definition.
By default, Metals runs an embedded
sbt-launch.jar launcher that respects
However, the environment variables
JAVA_OPTS are not respected.
Update the server property
-Dmetals.sbt-script=/path/to/sbt to use a custom
sbt script instead of the default Metals launcher if you need further
customizations like reading environment variables.
The "Import build" step can take a long time, especially the first time you run it in a new build. The exact time depends on the complexity of the build and if library dependencies need to be downloaded. For example, this step can take everything from 10 seconds in small cached builds up to 10-15 minutes in large uncached builds.
Consult the Bloop documentation to learn how to speed up build import.
When you change
build.sbt or sources under
project/, you will be prompted to
re-import the build.
You can annotate your stack trace with code lenses (which requires the
following bit of configuration mentioned earlier:
(lsp-mode . lsp-lens-mode)).
These allow you to run actions from your code.
One of these actions allow you to navigate your stack trace.
You can annotate any stack trace by marking a stack trace with your
region and using
M-x lsp-metals-analyze-stacktrace on it.
This will open a new Scala buffer that has code lenses annotations: just click on the small "open" annotation to navigate to the source code relative to your stack trace.
This will work as long as the buffer your are marking your stack trace
on exists within the project directory tracked by
lsp-metals-analyze-stacktrace needs the
lsp workspace to find the
location of your errors.
Note that if you try to do that from
sbt-mode, you may get an error
unless you patch
lsp-find-workspace with the following:
The above shall become unnecessary once this issue is solved.
To manually trigger a build import, run
M-x lsp-metals-doctor-run to troubleshoot potential configuration problems
in your build.
There is an alternative LSP client called eglot that might be worth trying out if you want to use an alternative to lsp-mode.
To configure Eglot with Metals:
If you start Emacs now then it will fail since the
metals-emacs binary does
not exist yet.
Next, build a
metals-emacs binary for the latest Metals release using the
Coursier command-line interface.
|0.10.7||16 Sep 2021 16:28|
|0.10.7+17-f589e8b6-SNAPSHOT||18 Sep 2021 10:35|
Make sure the generated
metals-emacs binary is available on your
You can check version of your binary by executing
Configure the system properties
if you are behind an HTTP proxy.
-Dmetals.client=emacs flag is important since it configures Metals for
usage with Emacs.
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: