> ## Documentation Index
> Fetch the complete documentation index at: https://metals-lsp.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Java and Scala Language Server

> Metals v2 is a language server for multi-million line Java and Scala codebases

<Tip>
  Latest version: <strong id="metals-version" style={{ cursor: "pointer" }} title="Click to copy">2.0.0-M2</strong><span id="metals-release-date-wrapper" style={{ display: "none" }}> (released <span id="metals-release-date" />)</span>
</Tip>

## 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](https://github.com/google/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](https://github.com/scalameta/metals),
the same repository as [Metals v1](https://scalameta.org/metals), 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.

<CardGroup cols={2}>
  <Card title="Fast" icon="bolt">
    Indexes \~1M lines/second. Usable in 10-20s even on massive codebases.
  </Card>

  <Card title="Build-Independent" icon="wand-magic-sparkles">
    Navigation works immediately. Build integration optional for high-fidelity analysis and testing/debugging.
  </Card>

  <Card title="Real-time Diagnostics" icon="clock">
    Errors appear as you type, not after you save and wait for compilation.
  </Card>

  <Card title="Bazel Friendly" icon="cubes">
    Import any symbol in the repo. Run Gazelle later to update your BUILD files.
  </Card>
</CardGroup>

***

## Installation

<CardGroup cols={3}>
  <Card title="Cursor" icon="window" href="/cursor">
    Install for Cursor
  </Card>

  <Card title="VS Code" icon="window" href="/vscode">
    Install for VS Code
  </Card>

  <Card title="Neovim" icon="window" href="/neovim">
    Install for Neovim
  </Card>
</CardGroup>

***

## Build Tool Integration

Build integration is optional but required for 3rd-party deps and test/debug.

| Build Tool | Status                                                  |
| ---------- | ------------------------------------------------------- |
| sbt        | <Icon icon="circle-check" iconType="solid" /> Supported |
| Mill       | <Icon icon="circle-check" iconType="solid" /> Supported |
| Bazel      | <Icon icon="wrench" iconType="solid" /> Setup required  |
| Gradle     | <Icon icon="wrench" iconType="solid" /> Setup required  |
| Maven      | <Icon icon="wrench" iconType="solid" /> Setup required  |

***

## Feature Support

| Feature              | Java                                          | Scala                                         |
| -------------------- | --------------------------------------------- | --------------------------------------------- |
| Diagnostics          | <Icon icon="circle-check" iconType="solid" /> | <Icon icon="circle-check" iconType="solid" /> |
| Go to definition     | <Icon icon="circle-check" iconType="solid" /> | <Icon icon="circle-check" iconType="solid" /> |
| Find references      | <Icon icon="circle-check" iconType="solid" /> | <Icon icon="circle-check" iconType="solid" /> |
| Find implementations | <Icon icon="circle-check" iconType="solid" /> | <Icon icon="circle-check" iconType="solid" /> |

***

***

## 3rd-Party Dependencies

Metals v2 indexes 1st-party sources out of the box. For 3rd-party dependencies,
create a `.metals/mbt.json` file:

```json theme={null}
{
  "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`](https://github.com/scalameta/metals/blob/main-v2/bin/extract-mbt.ts) script.

**Install Bun:**

```bash theme={null}
curl -fsSL https://bun.sh/install | bash
```

**Run the script:**

```bash theme={null}
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

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

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

<CardGroup cols={3}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/scalameta/metals/issues">
    Report bugs or request features
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.gg/v6qdXEmdeG">
    Chat with the community
  </Card>

  <Card title="Bazel Slack" icon="slack" href="https://bazelbuild.slack.com/archives/C0A8ZMZSHL0">
    \#metals-lsp channel
  </Card>
</CardGroup>