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/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.4-67-c910a45b

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": {
"showInferredType": 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": {
"showImplicitArguments": 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": {
"showImplicitConversionsAndClasses": 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
}
}

Remote language server

A URL pointing to an endpoint that implements a remote language server.

See https://scalameta.org/metals/docs/integrations/remote-language-server for documentation on remote language servers.

Default: empty string "".

Example:

{
"metals": {
"remoteLanguageServer": "https://language-server.company.com/message"
}
}

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.2.1

Example:

{
"metals": {
"fallbackScalaVersion": 3.2.1
}
}

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"
}
}