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 5.3.1 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. Should be an absolute path 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. Should be an absolute path 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

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

Example:

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

Should display lenses with links to super methods#

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

Should try adjust indentation on range formatting.#

When this option is enabled, when user pastes any snippet 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/contributors/remote-language-server.html 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: 2.12.15

Example:

{
"metals": {
"fallbackScalaVersion": 2.12.15
}
}