Skip to main content
Latest version: 2.0.0-M2 (released )

​
The Problem

Java and Scala IDEs depend on syncing with your build tool to understand the project structure. This sync is traditionally a blocking operation — often taking minutes on large codebases — and it’s brittle: when it fails or gets stuck, your IDE is useless until you fix it. This was tolerable when all code editing was done manually by developers. It’s not tolerable when an AI agent can implement a feature faster than your IDE can finish syncing. The JVM is an incredibly powerful platform, but its tooling hasn’t kept pace with how code is written today: remote environments, fast iteration cycles, and codebases measured in millions of lines.

​
The Approach

Metals v2 indexes source files directly, bypassing the build for core navigation. Open a repo with 10 million lines of code and you’re up and running within 20 seconds — no build server required, no need for the code to compile first.
  • Cold start: ~1 million lines per second
  • After initial index: Navigation is instant
For Java, Metals v2 uses Turbine, Google’s header compiler, to extract type information without full compilation. For Scala, it leverages the compiler’s -sourcepath option to resolve symbols efficiently directly from source. More architectural details will be shared in the future. Metals v2 is developed in scalameta/metals, the same repository as Metals v1, the official Scala language server. While v1 remains the stable choice for smaller projects, v2 is purpose-built for large codebases where build-dependent tooling becomes a bottleneck.

Fast

Indexes ~1M lines/second. Usable in 10-20s even on massive codebases.

Build-Independent

Navigation works immediately. Build integration optional for high-fidelity analysis and testing/debugging.

Real-time Diagnostics

Errors appear as you type, not after you save and wait for compilation.

Bazel Friendly

Import any symbol in the repo. Run Gazelle later to update your BUILD files.

​
Installation

Cursor

Install for Cursor

VS Code

Install for VS Code

Neovim

Install for Neovim

​
Build Tool Integration

Build integration is optional but required for 3rd-party deps and test/debug.
Build ToolStatus
sbt Supported
Mill Supported
Bazel Setup required
Gradle Setup required
Maven Setup required

​
Feature Support

FeatureJavaScala
Diagnostics
Go to definition
Find references
Find implementations

​
3rd-Party Dependencies

Metals v2 indexes 1st-party sources out of the box. For 3rd-party dependencies, create a .metals/mbt.json file: 
{
  "dependencyModules": [
    {
      "id": "com.google.guava:guava:33.5.0-jre",
      "jar": "/path/to/guava.jar",
      "sources": "/path/to/guava-sources.jar"
    }
  ]
}
Reload the window to navigate to external deps.

​
Generating mbt.json for Maven/Gradle

For Maven and Gradle projects, you can generate mbt.json automatically using the extract-mbt.ts script. Install Bun: 
curl -fsSL https://bun.sh/install | bash
Run the script: 
curl -fsSL https://raw.githubusercontent.com/scalameta/metals/main-v2/bin/extract-mbt.ts | bun -
The script auto-detects Maven (pom.xml) or Gradle (build.gradle) and writes .metals/mbt.json with all resolved dependencies. Options:
  • --maven or --gradle to force a specific build tool
  • --sources to download source JARs before extraction
The script is intentionally simple. Download it locally and modify it for your specific build setup—use AI assistants to help debug or extend it.

​
Generated Code

Generated sources (e.g. from Protobuf) require a BSP server. As a workaround, add them as entries in mbt.json.

​
Known Limitations

Java support has gaps compared to mature Java IDEs.

​
Java Code Actions

Limited to import suggestions. Refactorings (extract method, inline variable, move class) are not implemented. Scala has broader support.

​
Test & Debug

Requires a BSP server that supports DAP. Setup is more involved than other features.

​
Getting Help

GitHub Issues

Report bugs or request features

Discord

Chat with the community

Bazel Slack

#metals-lsp channel