Skip to main content

Metals User Configuration

While each editor may have a different way to change the user configuration, the values should be more or less the same for all extensions. Below you'll find all the available configuration options and what they do.

Java Home directory​

The Java Home directory used for indexing JDK sources and locating the java binary.

Default: JAVA_HOME environment variable with fallback to user.home system property.

Example:

{
  "metals": {
    "javaHome": "/Library/Java/JavaVirtualMachines/jdk1.8.0_192.jdk/Contents/Home"
  }
}

sbt script​

Optional absolute path to an sbt executable to use for running sbt bloopInstall. By default, Metals uses java -jar sbt-launch.jar with an embedded launcher while respecting .jvmopts and .sbtopts. Update this setting if your sbt script requires more customizations like using environment variables.

Default: empty string "".

Example:

{
  "metals": {
    "sbtScript": "/usr/local/bin/sbt"
  }
}

Gradle script​

Optional absolute path to a gradle executable to use for running gradle bloopInstall. By default, Metals uses gradlew with 7.5.0 gradle version. Update this setting if your gradle script requires more customizations like using environment variables.

Default: empty string "".

Example:

{
  "metals": {
    "gradleScript": "/usr/local/bin/gradle"
  }
}

Maven script​

Optional absolute path to a maven executable to use for generating bloop config. By default, Metals uses mvnw maven wrapper with 3.6.1 maven version. Update this setting if your maven script requires more customizations

Default: empty string "".

Example:

{
  "metals": {
    "mavenScript": "/usr/local/bin/mvn"
  }
}

Mill script​

Optional absolute path to a mill executable to use for running mill mill.contrib.bloop.Bloop/install. By default, Metals uses mill wrapper script with 0.5.0 mill version. Update this setting if your mill script requires more customizations like using environment variables.

Default: empty string "".

Example:

{
  "metals": {
    "millScript": "/usr/local/bin/mill"
  }
}

Scalafmt config path​

Optional custom path to the .scalafmt.conf file. It should be a path (relative or absolute - though an absolute path is recommended) and use forward slashes / for file separators (even on Windows).

Default: empty string "".

Example:

{
  "metals": {
    "scalafmtConfigPath": "project/.scalafmt.conf"
  }
}

Scalafix config path​

Optional custom path to the .scalafix.conf file. It should be a path (relative or absolute - though an absolute path is recommended) and use forward slashes / for file separators (even on Windows).

Default: empty string "".

Example:

{
  "metals": {
    "scalafixConfigPath": "project/.scalafix.conf"
  }
}

Ammonite JVM Properties​

Optional list of JVM properties to pass along to the Ammonite server. Each property needs to be a separate item.\n\nExample: -Xmx1G or -Xms100M"

Default: [].

Example:

{
  "metals": {
    "ammoniteJvmProperties": ["-Xmx1G"]
  }
}

Excluded Packages​

Packages that will be excluded from completions, imports, and symbol searches.

Note that this is in addition to some default packages that are already excluded. The default excluded packages are listed below:

META-INF
images
toolbarButtonGraphics
jdk
sun
oracle
java.awt.desktop
org.jcp
org.omg
org.graalvm
com.oracle
com.sun
com.apple
apple
com.sourcegraph.shaded

If there is a need to remove one of the defaults, you are able to do so by including the package in your list and prepending -- to it.

Example:

["--sun"]

Default: [].

Example:

{
  "metals": {
    "excludedPackages": ["akka.actor.typed.javadsl"]
  }
}

Don't generate Bloop plugin file for sbt​

If true, Metals will not generate metals.sbt files under the assumption that sbt-bloop is already manually installed in the sbt build. Build import will fail with a 'not valid command bloopInstall' error in case Bloop is not manually installed in the build when using this option.

Default: false

Example:

{
  "metals": {
    "bloopSbtAlreadyInstalled": false
  }
}

Version of Bloop​

This version will be used for the Bloop build tool plugin, for any supported build tool, while importing in Metals as well as for running the embedded server

Default: 1.5.17

Example:

{
  "metals": {
    "bloopVersion": "1.4.0-RC1"
  }
}

Bloop JVM Properties​

Optional list of JVM properties to pass along to the Bloop server. Please follow this guide for the format https://scalacenter.github.io/bloop/docs/server-reference#global-settings-for-the-server"

Default: ["-Xmx1G"].

Example:

{
  "metals": {
    "bloopJvmProperties": ["-Xmx1G"]
  }
}

Super method lenses are visible above methods definition that override another methods. Clicking on a lens jumps to super method definition. Disabled lenses are not calculated for opened documents which might speed up document processing.

Default: false

Example:

{
  "metals": {
    "superMethodLensesEnabled": false
  }
}

Should display type annotations for inferred types​

When this option is enabled, each method that can have inferred types has them displayed either as additional decorations if they are supported by the editor or shown in the hover.

Default: false

Example:

{
  "metals": {
    "inlayHints.inferredTypes.enable": false
  }
}

Should display implicit parameter at usage sites​

When this option is enabled, each method that has implicit arguments has them displayed either as additional decorations if they are supported by the editor or shown in the hover.

Default: false

Example:

{
  "metals": {
    "inlayHints.implicitArguments.enable": false
  }
}

Should display implicit conversion at usage sites​

When this option is enabled, each place where an implicit method or class is used has it displayed either as additional decorations if they are supported by the editor or shown in the hover.

Default: false

Example:

{
  "metals": {
    "inlayHints.implicitConversions.enable": false
  }
}

Should display type annotations for type parameters​

When this option is enabled, each place when a type parameter is applied has it displayed either as additional decorations if they are supported by the editor or shown in the hover.

Default: false

Example:

{
  "metals": {
    "inlayHints.typeParameters.enable": false
  }
}

Should display type annotations in pattern matches​

When this option is enabled, each place when a type is inferred in a pattern match has it displayed either as additional decorations if they are supported by the editor or shown in the hover.

Default: false

Example:

{
  "metals": {
    "inlayHints.hintsInPatternMatch.enable": false
  }
}

Use semantic tokens highlight​

When this option is enabled, Metals will provide semantic tokens for clients that support it. The feature should work within all supported files extensions aside from Java.

Default: true

Example:

{
  "metals": {
    "enableSemanticHighlighting": false
  }
}

Indent snippets when pasted.​

When this option is enabled, when a snippet is pasted into a Scala file, Metals will try to adjust the indentation to that of the current cursor.

Default: false

Example:

{
  "metals": {
    "enableIndentOnPaste": false
  }
}

Default fallback Scala version​

The Scala compiler version that is used as the default or fallback in case a file doesn't belong to any build target or the specified Scala version isn't supported by Metals. This applies to standalone Scala files, worksheets, and Ammonite scripts.

Default: 3.3.3

Example:

{
  "metals": {
    "fallbackScalaVersion": 3.3.3
  }
}

Test UI used for tests and test suites​

Default way of handling tests and test suites. The only valid values are "code lenses" and "test explorer". See https://scalameta.org/metals/docs/integrations/test-explorer for information on how to work with the test explorer.

Default: Code Lenses

Example:

{
  "metals": {
    "testUserInterface": test explorer
  }
}

Eclipse Java formatter config path​

Optional custom path to the eclipse-formatter.xml file. It should be a path (relative or absolute - though an absolute path is recommended) and use forward slashes / for file separators (even on Windows).

Default: empty string "".

Example:

{
  "metals": {
    "javaFormat.eclipseConfigPath": "formatters/eclipse-formatter.xml"
  }
}

Eclipse Java formatting profile​

If the Eclipse formatter file contains more than one profile, this option can be used to control which is used.

Default: empty string "".

Example:

{
  "metals": {
    "javaFormat.eclipseProfile": "GoogleStyle"
  }
}

Scala CLI launcher​

Optional absolute path to a scala-cli executable to use for running a Scala CLI BSP server. By default, Metals uses the scala-cli from the PATH, or it's not found, downloads and runs Scala CLI on the JVM (slower than native Scala CLI). Update this if you want to use a custom Scala CLI launcher, not available in PATH.

Default: empty string "".

Example:

{
  "metals": {
    "scalaCliLauncher": "/usr/local/bin/scala-cli"
  }
}

Custom project root​

Optional relative path to your project's root. If you want your project root to be the workspace/workspace root set it to "." .

Default: empty string "".

Example:

{
  "metals": {
    "customProjectRoot": "backend/scalaProject/"
  }
}

Show all compilation debugging information​

If a build server supports it (for example Bloop or Scala CLI), setting it to true will make the logs contain all the possible debugging information including about incremental compilation in Zinc.

Default: false

Example:

{
  "metals": {
    "verboseCompilation": true
  }
}

Import build when changes detected without prompting​

Automatically import builds rather than prompting the user to choose. "initial" will only automatically import a build when a project is first opened, "all" will automate build imports after subsequent changes as well.

Default: off

Example:

{
  "metals": {
    "autoImportBuild": all
  }
}

Default to using build tool as your build server.​

If your build tool can also serve as a build server, default to using it instead of Bloop.

Default: false

Example:

{
  "metals": {
    "defaultBspToBuildTool": true
  }
}