To run scalafix on your project, you must first install the Scalafix sbt plugin or command line interface. Currently, Scalafix does not provide any IDE integrations with IntelliJ/ENSIME.


The sbt-plugin is the recommended integration to run semantic rules like RemoveUnusedImports or ExplicitResultTypes.

// ===> project/plugins.sbt
addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.5.10")

// ===> sbt shell
> scalafixEnable // Setup scalafix for active session.
                 // Not needed if build.sbt is configured like below.
> scalafixCli                                            // Run all rules configured in .scalafix.conf
> scalafixCli --rules RemoveUnusedImports                 // Run only RemoveUnusedImports rule
> myProject/scalafixCli --rules RemoveUnusedImports       // Run rule in one project only
> test:scalafixCli --rules RemoveUnusedImports            // Run rule in single configuration
> scalafixCli --rules ExplicitR<TAB>                      // Use tab completion
> scalafixCli --rules replace:com.foobar/com.buzbaz       // Refactor (experimental)
> scalafixCli --rules file:rules/MyRule.scala             // Run local custom rule
> scalafixCli --rules github:org/repo/v1                  // Run library migration rule
> scalafixCli --test                                      // Make sure no files needs to be fixed

// (optional, to avoid need for scalafixEnable) permanently enable scalafix in build.sbt
// ===> build.sbt
scalaVersion := "2.12.4" // 2.11.12 is also supported.

// If you get "-Yrangepos is required" error or "Missing compiler plugin semanticdb",
// This setting must appear after scalacOptions and libraryDependencies.
// or scalafixLibraryDependencies (Add semanticdb-scalac compiler plugin to libraryDependencies.)
// & scalacOptions bellow

// Similarly for sbt builds

// To configure for custom configurations like IntegrationTest
scalafixConfigure(Compile, Test, IntegrationTest)

Verify installation

To verify the installation, check that scalacOptions and libraryDependecies contain the values below.

> show scalacOptions
[info] * -Yrangepos                   // required
[info] * -Xplugin-require:semanticdb  // recommended
[info] * -P:semanticdb:sourceroot:/x  // recommended
> show libraryDependencies
[info] * org.scalameta:semanticdb-scalac:2.1.7:plugin->default(compile)

Example project

For a minimal example project using sbt-scalafix, see the scalacenter/scalafix-sbt-example repository.

git clone
cd scalafix-sbt-example
sbt "scalafix RemoveUnusedImports"
git diff // should produce a diff

Settings and tasks

Name Type Description
scalafixCli <args> Unit Invoke scalafix command line interface directly. See cli or use tab completion to explore supported arguments
scalafix <rule>.. Unit Run scalafix on project sources. See Rules or use tab completion to explore supported rules.
scalafixTest <rule>.. Unit Similar to the above task with the –test parameter
sbtfix <rule>.. Unit Run scalafix on the build sources, *.sbt and project/*. Note: Only supports syntactic rules.
sbtfixTest <rule>.. Unit Similar to the above task with the –test parameter
scalafixConfig Option[File] .scalafix.conf file to specify which scalafix rules should run.
scalafixScalacOptions Seq[String] Necessary Scala compiler settings for scalafix to work.
scalafixScalaVersion String Which Scala version of scalafix-cli to run.
scalafixSemanticdbVersion String Which version of org.scalameta:semanticdb-scalac to run.
scalafixSourceRoot File The root directory of this project.
scalafixVerbose Boolean If true, print out debug information.
scalafixVersion String Which version of scalafix-cli to run.
scalafixEnabled Boolean Deprecated. Use the scalafixEnable command or manually configure scalacOptions/libraryDependecies/scalaVersion
scalametaSourceroot File Deprecated. Renamed to scalafixSourceroot


⚠️ Experimental

semanticdb-sbt is a Scala 2.10 compiler plugin that extracts semantic information from the sbt compiler. Note. semanticdb-sbt only works for *.scala files, it does not support *.sbt files.

// project/plugins.sbt
addCompilerPlugin("org.scalameta" % "semanticdb-sbt" % "0.4.0" cross CrossVersion.full)

Once enabled, you can run scalafix rules against project/*.scala:

> reload // rebuild semanticdb for project/*.scala sources
> sbtfix Sbt1


The recommended way to install the scalafix command-line interface is with coursier.


// coursier
coursier bootstrap ch.epfl.scala:scalafix-cli_2.12.4:0.5.10 -f --main scalafix.cli.Cli -o scalafix
./scalafix --help


// homebrew
brew install --HEAD olafurpg/scalafmt/scalafix
scalafix --help


// wget
wget -O scalafix
./scalafix --help

Once the scalafix cli is installed, consult the –help page for further usage instructions.


scalafix 0.5.10-20180618-1437
Usage: scalafix [options] [<file>...]
        Print usage and exit
  --help | -h  
        Print help message and exit
  --version | -v  
        Print version number and exit
        If set, print out debugging inforation to stderr.
  --config | -c  <.scalafix.conf>
        File path to a .scalafix.conf configuration file.
  --config-str | -c  <imports.organize=false>
        String representing scalafix configuration
  --sourceroot  </foo/myproject>
        Absolute path passed to semanticdb with
	-P:semanticdb:sourceroot:<path>. Relative filenames persisted in the
	Semantic DB are absolutized by the sourceroot. Defaults to current
	working directory if not provided.
  --classpath  <entry1.jar:entry2.jar:target/scala-2.12/classes/> separated list of directories or jars
	containing '.semanticdb' files. The 'semanticdb' files are emitted by
	the semanticdb-scalac compiler plugin and are necessary for semantic
	rules like ExplicitResultTypes to function.
  --classpath-auto-roots  <value>
        Automatically infer --classpath starting from these directories.
	Ignored if --classpath is provided.
  --tool-classpath  <entry1.jar:entry2.jar:target/scala-2.12/classes/>
        Additional classpath to use when classloading/compiling rules
        Disable validation when loading semanticdb files.
  --rules | -r  <ProcedureSyntax OR file:LocalFile.scala OR scala:full.Name OR>
        Scalafix rules to run.
        If set, print fix to stdout instead of writing to file.
        Exit non-zero code if files have not been fixed. Won't write to files.
  --out-from  </shared/>
        Regex that is passed as first argument to
	fileToFix.replaceAll(outFrom, outTo)
  --out-to  </custom/>
        Replacement string that is passed as second argument to
	fileToFix.replaceAll(outFrom, outTo)
  --exclude  <core Foobar.scala>
        Space separated list of regexes to exclude which files to fix. If a
	file match one of the exclude regexes, then it will not get fixed.
	Defaults to excluding no files.
        If true, run on single thread. If false (default), use all available
        If true, does not sys.exit at the end. Useful for example in
        Don't report parse errors for non-explictly passed filepaths.
        Print out bash completion file for scalafix. To install on scalafix
	--bash > /usr/local/etc/bash_completion.d/scalafix # Mac scalafix
	--bash > /etc/bash_completion.d/scalafix # Linux
        Print out zsh completion file for scalafix. To install: scalafix --zsh
	> /usr/local/share/zsh/site-functions/_scalafix
        Don't use fancy progress bar.
  --project-id  <value>
        String ID to prefix reported messages with
        If set, only apply scalafix to added and edited files in git diff
	against master.
  --diff-base  <value>
        If set, only apply scalafix to added and edited files in git diff
	against a provided branch, commit or tag. (defaults to master)
Available rules: DottyKeywords, DisableSyntax, NoFinalize, NoValInForComprehension, RemoveXmlLiterals, LeakingImplicitClassVal, VolatileLazyVal, ProcedureSyntax, ExplicitUnit, DottyVolatileLazyVal, DottyVarArgPattern, NoInfer, Sbt1, ExplicitResultTypes, ExplicitReturnTypes, RemoveUnusedImports, RemoveUnusedTerms, NoAutoTupling, Disable, DisableUnless, MissingFinal

NOTE. The command line tool is mostly intended to be invoked programmatically
from build-tool integrations such as sbt-scalafix. The necessary fixture to run
semantic rules is tricky to setup manually.

Scalafix chooses which files to fix according to the following rules:
- scalafix <directory> <rule> finds *.scala files in <directory>
- when <rule> is semantic
  - if --classpath and --sourceroot are provided, then those are used to find .semanticdb files
  - otherwise, Scalafix will automatically look for META-INF/semanticdb directories from the
    current working directory.
- when --diff or --diff-branch is set it will parse the git diff and only
  apply on modified or added lines

  Those command will have the same effect:
    scalafix --diff
    scalafix --diff-branch=master

Examples (semantic):
  $ scalafix # automatically finds .semanticdb files and runs rule configured in .scalafix.conf.
  $ scalafix <directory> # same as above except only run on files in <directory>
  $ scalafix --rules RemoveUnusedImports # same as above but run RemoveUnusedImports.
  $ scalafix --classpath <foo.jar:target/classes> # explicitly pass classpath, --sourceroot is cwd.
  $ scalafix --classpath <foo.jar:target/classes> --sourceroot <directory>
  $ cat .scalafix.conf
  rules = [ProcedureSyntax]
  $ scalafix Code.scala # Same as --rules ProcedureSyntax

Exit status codes:


It is possible to use scalafix with scala-maven-plugin but it requires a custom setup since there is no scalafix specific Maven plugin.

Install semanticdb compiler plugin

First, download the semanticdb-scalac compiler plugin which corresponds to your exact scala version of your project, down to the patch number.

To begin with, it’s recommended to install the coursier command line interface

wget && chmod +x coursier && ./coursier --help

Coursier is a tool to download and launch library artifacts. Once you have coursier installed, assuming you are on 2.12.4:

coursier fetch --intransitive org.scalameta:semanticdb-scalac_2.12.4:2.1.7

You can also use wget or a simalar tool to retrieve the jar from

Compile sources with semanticdb

Let’s say the semanticdb-scalac_2.12.4-2.1.7.jar is available in PLUGINS/semanticdb-scalac_2.12.4-2.1.7.jar path on your file system.

Recompile your project using -DaddScalacArgs as follow:

mvn clean test -DskipTests=true -DaddScalacArgs="-Yrangepos|-Xplugin-require:semanticdb|-Xplugin:PLUGIN/semanticdb-scalac_2.12.4-2.1.7.jar|-Ywarn-unused-import"

Here, we compile both main sources and tests to have semantic information generated for all of them, but we skip test execution because it is not the point of that compilation. The added flags for scala are given with the addScalaArgs option (see

  • -Yrangepos is required for semanticdb to function properly,
  • -Xplugin:PLUGIN/semanticdb-scalac_2.12.4-2.1.7.jar give the path where the semanticdb jar can be found,
  • (optional) -Xplugin-require:semanticdb tells scalac to fails if it can’t load the semanticdb plugin,
  • (optional) -Ywarn-unused-import is required for the RemoveUnusedImports rule. If you don’t run RemoveUnusedImports you can skip this flag. Consult the scalafix documentation for each rule to see which flags it requires.
  • (optional) Customize the –sourceroot with -P:semanticdb:sourceroot:/path/to/sourceroot (more details below)

After compilation, double check that there exists a directory target/classes/META-INF/semanticdb/ containing files with the .semanticdb extension.

Important note: you will need to recompile to get up-to-date semanticdb information after each modification.

Run scalafix-cli

Install and use scalafix as explained above. One important note is that you need to give --sourceroot with the root path the same as the path where you ran your mvn clent test command. This may be confusing when you are on a multi-module project. For example, if your project is:

 |- moduleA
 |    |- src/{main, test}/scala
 |    `- target
 `- moduleB
      |- src/{main, test}/scala
      `- target

If you compile at scalaProject level, you will need to invoke scalafix with:

scalafix --rules RemoveUnusedImports --sourceroot /path/to/somepath/scalaProject

But if you compiled at moduleA level only, you will need to use:

scalafix --rules RemoveUnusedImports --sourceroot /path/to/somepath/scalaProject/moduleA


Scalafix can be used as a library to run custom rules.

// ===> build.sbt
libraryDependencies += "ch.epfl.scala" %% "scalafix-core" % "0.5.10"
// (optional) Scala.js is also supported
libraryDependencies += "ch.epfl.scala" %%% "scalafix-core" % "0.5.10"

Example usage of the syntactic API.

import scalafix._
import scala.meta._

case object Uppercase extends Rule("Uppercase") {
  override def fix(ctx: RuleCtx): Patch =
    ctx.tree.collect {
      case name @ Name(value) => ctx.replaceTree(name, value.toUpperCase())

println(Uppercase("object Hello { println('world) }"))
// object HELLO { PRINTLN('world) }

The semantic API requires a more complicated setup. Please see Rule Authors.


Our CI publishes a snapshot release to Sonatype on every merge into master. Each snapshot release has a unique version number, jars don’t get overwritten. To find the latest snapshot version number, go to and select the version number at the bottom, the one with the latest “Last Modified”. Once you have found the version number, adapting the version number

// If using sbt-scalafix, add to project/plugins.sbt
resolvers += Resolver.sonatypeRepo("snapshots")
addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.5.10-20180618-1437-SNAPSHOT")

// If using scalafix-cli, launch with coursier
coursier launch ch.epfl.scala:scalafix-cli_2.12.4:0.5.10-20180618-1437-SNAPSHOT -r sonatype:snapshots --main scalafix.cli.Cli -- --help