Skip to main content


helix demo


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.12, 2.12.13, 2.12.14, 2.12.15, 2.12.16, 2.12.17, 2.12.18, 2.12.19

  • Scala 2.13: 2.13.7, 2.13.8, 2.13.9, 2.13.10, 2.13.11, 2.13.12, 2.13.13, 2.13.14

  • Scala 3: 3.3.1, 3.2.2, 3.3.2, 3.1.3, 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


Helix requires metals to be on the user's path, it should then be automatically detected and enabled. Installing metals in this manner is most readily achieved via Coursier, running coursier install metals should be sufficient. To check that Helix is able to detect metals after this run hx --health scala

Importing builds

At present Helix does not support the LSP features to have metals prompt the user to import the build as it does in other editors and therefore the responsibility falls to the user to import manually whenever the build is updated.

To manually import a build run the :lsp-workspace-command command and then select build-import from the list.

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