Introduction to Mill

Mill is your shiny new Java/Scala build tool! Scared of SBT? Melancholy over Maven? Grumbling about Gradle? Baffled by Bazel? Give Mill a try!

Mill aims for simplicity by reusing concepts you are already familiar with, borrowing ideas from modern tools like Bazel. It lets you build your projects in a way that’s simple, fast, and predictable.

Mill has built-in support for the Scala programming language, and can serve as a replacement for SBT. It can be extended to support any other language or platform via modules (written in Java or Scala) or through external subprocesses.

If you are using Mill, you will find the following book by the Author useful in using Mill to the fullest:



Installation via homebrew:

brew install mill

Arch Linux

Arch Linux has a Community package for mill:

pacman -S mill


Installation via pkg(8):

pkg install mill

Gentoo Linux

emerge dev-java/mill-bin


To get started, download Mill from Github releases, and save it as mill.bat.

If you’re using Scoop you can install Mill via

scoop install mill

Mill also works on "sh" environments on Windows (e.g., MSYS2, Cygwin, Git-Bash, WSL); to get started, follow the instructions in the Manual section below. Note that:

  • In some environments (such as WSL), Mill might have to be run without a server (using -i, --interactive , --no-server, or --repl.)

  • On Cygwin, run the following after downloading mill:

sed -i '0,/-cp "\$0"/{s/-cp "\$0"/-cp `cygpath -w "\$0"`/}; 0,/-cp "\$0"/{s/-cp "\$0"/-cp `cygpath -w "\$0"`/}' /usr/local/bin/mill


You can download and run a "Docker image containing OpenJDK, Scala and Mill" using

docker pull nightscape/scala-mill
docker run -it nightscape/scala-mill


To get started, download Mill and install it into your system via the following curl/chmod command:

sudo sh -c "curl -L > /usr/local/bin/mill && chmod +x /usr/local/bin/mill"

Bootstrap Scripts (Linux/OS-X Only)

If you are using Mill in a codebase, you can commit the bootstrap launcher as a ./mill script in the project folder:

curl -L > mill && chmod +x mill

Now, anyone who wants to work with the project can simply use the ./mill script directly:

./mill version
./mill __.compile # double underscore

The mill command will automatically use the version specified by the bootstrap script, even if you installed it via other means. The ./mill file has a version number embedded within it, which you can update simply by editing the script. Note this only works for versions 0.5.0 and above.

Bootstrap scripts are also useful for running Mill in CI, ensuring that your Jenkins/Travis/etc. box has the correct version of Mill present to build/compile/test your code.


Instead of installing Mill directly, you can also use lefou/millw as drop-in replacement for mill. It provides a small shell script and also a Windows batch file, that transparently downloads mill and executes it on your behalf. It respects various ways to configure the preferred Mill version (MILL_VERSION env var, .mill-version file, --mill-version option) and can also be used as a bootstrap script in your project.

Coursier (unsupported)

Installing mill via coursier or cs is currently not officially supported. There are various issues, especially with interactive mode.

Updating Mill

Once installed mill is able to use newer or different versions for each project automatically. You don’t need to install multiple versions of mill yourself.

See section Overriding Mill Versions how to do it.

Getting Started

The simplest Mill build for a Java project looks as follows:
import mill._, scalalib._

object foo extends JavaModule {}

The simplest Mill build for a Scala project looks as follows:
import mill._, scalalib._

object foo extends ScalaModule {
  def scalaVersion = "2.13.8"

Both of these would build a project laid out as follows:

You can download an example project with this layout here:

The source code for this module would live in the foo/src/ folder, matching the name you assigned to the module. Output for this module (compiled files, resolved dependency lists, …) would live in out/foo/.

This can be run from the Bash shell via:

$ mill foo.compile                 # compile sources into classfiles

$ mill                     # run the main method, if any

$ mill foo.runBackground           # run the main method in the background

$ mill foo.launcher                # prepares a foo/launcher.dest/run you can run later

$ mill foo.jar                     # bundle the classfiles into a jar

$ mill foo.assembly                # bundle classfiles and all dependencies into a jar

$ mill -i foo.console              # start a Scala console within your project (in interactive mode: "-i")

$ mill -i foo.repl                 # start an Ammonite REPL within your project (in interactive mode: "-i")

You can run mill resolve __ to see a full list of the different tasks that are available, mill resolve foo._ to see the tasks within foo, mill inspect foo.compile to inspect a task’s doc-comment documentation or what it depends on, or mill show foo.scalaVersion to show the output of any task.

The most common tasks that Mill can run are cached targets, such as compile, and un-cached commands such as Targets do not re-evaluate unless one of their inputs changes, whereas commands re-run every time.


Mill puts all its output in the top-level out/ folder. The above commands would end up in:







For each task there’s a foo.json file containing the metadata returned by that task, and two optional paths: a foo.dest/ folder containing any files that the task generates and a foo.log file containing the the logs of running that task. For example, out/foo/compile.dest/ contains the compiled classfiles, while out/foo/assembly.dest/ contains the self-contained assembly with the project’s classfiles jar-ed up with all its dependencies.

Given a task, all its output and results are inside its respective out/foo/bar/ folder.

Multiple Modules

Java Example
import mill._, scalalib._

object foo extends JavaModule

object bar extends JavaModule {
  def moduleDeps = Seq(foo)

Scala Example
import mill._, scalalib._

object foo extends ScalaModule {
  def scalaVersion = "2.13.8"

object bar extends ScalaModule {
  def moduleDeps = Seq(foo)

  def scalaVersion = "2.13.8"

You can define multiple modules the same way you define a single module, using def moduleDeps to define the relationship between them. The above builds expect the following project layout:

And can be built/run using:

$ mill foo.compile
$ mill bar.compile

$ mill
$ mill

$ mill foo.jar
$ mill bar.jar

$ mill foo.assembly
$ mill bar.assembly

Mill’s evaluator will ensure that the modules are compiled in the right order, and recompiled as necessary when source code in each module changes.

Modules can also be nested:
import mill._, scalalib._

object foo extends ScalaModule {
  def scalaVersion = "2.13.8"

  object bar extends ScalaModule {
    def moduleDeps = Seq(foo)

    def scalaVersion = "2.13.8"

Which would result in a similarly nested project layout:

Where the nested modules can be run via:

$ mill foo.compile
$ mill

$ mill
$ mill

$ mill foo.jar
$ mill

$ mill foo.assembly
$ mill

Watch and Re-evaluate

You can use the --watch flag to make Mill watch a task’s inputs, re-evaluating the task as necessary when the inputs change:

$ mill --watch foo.compile
$ mill --watch
$ mill -w foo.compile
$ mill -w

Mill’s --watch flag watches both the files you are building using Mill, as well as Mill’s own file and anything it imports, so any changes to your will automatically get picked up.

For long-running processes like web servers, you can use runBackground to make sure they recompile and restart when code changes, forcefully terminating the previous process even though it may be still alive:

$ mill -w foo.compile
$ mill -w foo.runBackground

Parallel Task Execution (Experimental)

By default, mill will evaluate all tasks in sequence. But mill also supports processing tasks in parallel. This feature is currently experimental and we encourage you to report any issues you find on our bug tracker.

To enable parallel task execution, use the --jobs (-j) option followed by a number of maximal parallel threads.

Example: Use up to 4 parallel threads to compile all modules:

mill -j 4 __.compile

To use as many threads as your machine has (logical) processor cores use --jobs 0. To disable parallel execution use --jobs 1. This is currently the default.

Please note that the maximal possible parallelism depends on your project. Tasks that depend on each other can’t be processed in parallel.

Command-line usage

Mill is a command-line tool and supports various options.

Run mill --help for a complete list of options

Output of mill --help
Mill Build Tool
usage: mill [options] [[target [target-options]] [+ [target ...]]]
  --no-default-predef  Disable the default predef and run Ammonite with the minimal predef possible
  -s --silent          Make ivy logs go silent instead of printing though failures will still throw
  -w --watch           Watch and re-run your scripts when they change
  --bsp                Run a BSP server against the passed scripts
  -c --code <str>      Pass in code to be run immediately in the REPL
  -h --home <path>     The home directory of the REPL; where it looks for config and caches
  -p --predef <path>   Lets you load your predef from a custom location, rather than the "default
                       location in your Ammonite home
  --color <bool>       Enable or disable colored output; by default colors are enabled in both REPL
                       and scripts if the console is interactive, and disabled otherwise
  --thin               Hide parts of the core of Ammonite and some of its dependencies. By default,
                       the core of Ammonite and all of its dependencies can be seen by users from
                       the Ammonite session. This option mitigates that via class loader isolation.
  --help               Print this message
  -h --home <path>     The home directory of the REPL; where it looks for config and caches
  --repl               Run Mill in interactive mode and start a build REPL. In this mode, no mill
                       server will be used. Must be the first argument.
  --no-server          Run Mill in interactive mode, suitable for opening REPLs and taking user
                       input. In this mode, no mill server will be used. Must be the first argument.
  -i --interactive     Run Mill in interactive mode, suitable for opening REPLs and taking user
                       input. In this mode, no mill server will be used. Must be the first argument.
  -v --version         Show mill version and exit.
  -b --bell            Ring the bell once if the run completes successfully, twice if it fails.
  --disable-ticker     Disable ticker log (e.g. short-lived prints of stages and progress bars)
  -d --debug           Show debug output on STDOUT
  -k --keep-going      Continue build, even after build failures
  -D --define <k=v>    Define (or overwrite) a system property
  -j --jobs <int>      Allow processing N targets in parallel. Use 1 to disable parallel and 0 to
                       use as much threads as available processors.
  rest <str>...        The name of the targets you want to build, followed by any parameters you
                       wish to pass to those targets.

All options must be given before the first target.

A target is a fully qualified task or command optionally followed by target specific arguments. You can use wildcards and brace-expansion to select multiple targets at once or to shorten the path to deeply nested targets. If you provide optional target arguments and your wildcard or brace-expansion is resolved to multiple targets, the arguments will be applied to each of the targets.

Table 1. Wildcards and brace-expansion




matches a single segment of the target path


matches arbitrary segments of the target path


is equal to specifying two targets a and b

You can use the + symbol to add another target with optional arguments. If you need to feed a + as argument to your target, you can mask it by preceding it with a backslash (\).


mill foo._.compile

Runs compile for all direct sub-modules of foo

mill foo.__.test

Runs test for all sub-modules of foo

mill {foo,bar}.__.testCached

Runs testCached for all sub-modules of foo and bar

mill __.compile + foo.__.test

Runs all compile targets and all tests under foo.

Command-line Tools

Mill comes with a few useful command-line utilities built into it:


$ mill resolve _
[1/1] resolve

$ mill resolve _.compile
[1/1] resolve

$ mill resolve foo._
[1/1] resolve

resolve lists the tasks that match a particular query, without running them. This is useful for "dry running" an mill command to see what would be run before you run them, or to explore what modules or tasks are available from the command line using resolve _, resolve foo._, etc.

mill resolve foo.{compile,run}
mill resolve "foo.{compile,run}"
mill resolve foo.compile
mill resolve _.compile          # list the compile tasks for every top-level module
mill resolve __.compile         # list the compile tasks for every module
mill resolve _                  # list every top level module and task
mill resolve foo._              # list every task directly within the foo module
mill resolve __                 # list every module and task recursively


$ mill inspect
[1/1] inspect
    Runs this module's code in a subprocess and waits for it to finish


inspect is a more verbose version of resolve. In addition to printing out the name of one-or-more tasks, it also displays its source location and a list of input tasks. This is very useful for debugging and interactively exploring the structure of your build from the command line.

inspect also works with the same _/__ wildcard/query syntaxes that resolve do:

mill inspect foo.compile
mill inspect foo.{compile,run}
mill inspect "foo.{compile,run}"
mill inspect foo.compile
mill inspect _.compile
mill inspect __.compile
mill inspect _
mill inspect foo._
mill inspect __


$ mill show foo.scalaVersion
[1/1] show

By default, Mill does not print out the metadata from evaluating a task. Most people would not be interested in e.g. viewing the metadata related to incremental compilation: they just want to compile their code! However, if you want to inspect the build to debug problems, you can make Mill show you the metadata output for a task using the show command:

show is not just for showing configuration values. All tasks return values that can be shown with show. E.g. compile returns the paths to the classes folder and analysisFile file produced by the compilation:

$ mill show foo.compile
[1/1] show
[10/25] foo.resources
    "analysisFile": "/Users/lihaoyi/Dropbox/Github/test//out/foo/compile.dest/zinc",
    "classes": "ref:07960649:/Users/lihaoyi/Dropbox/Github/test//out/foo/compile.dest/classes"

show is generally useful as a debugging tool, to see what is going on in your build:

$ mill show foo.sources
[1/1] show
[1/1] foo.sources

$ mill show foo.compileClasspath
[1/1] show
[2/11] foo.resources

show is also useful for interacting with Mill from external tools, since the JSON it outputs is structured and easily parsed and manipulated.


$ mill path foo.assembly foo.sources
[1/1] path

mill path prints out a dependency chain between the first task and the second. It is very useful for exploring the build graph and trying to figure out how data gets from one task to another. If there are multiple possible dependency chains, one of them is picked arbitrarily.


$ mill plan foo.compileClasspath
[1/1] plan

mill plan foo shows which tasks would be evaluated, and in what order, if you ran mill foo, but without actually running them. This is a useful tool for debugging your build: e.g. if you suspect a task foo is running things that it shouldn’t be running, a quick mill plan will list out all the upstream tasks that foo needs to run, and you can then follow up with mill path on any individual upstream task to see exactly how foo depends on it.


$ mill show visualize foo._
[1/1] show
[3/3] visualize

mill show visualize takes a subset of the Mill build graph (e.g. core._ is every task directly under the core module) and draws out their relationships in .svg and .png form for you to inspect. It also generates .txt, .dot and .json for easy processing by downstream tools.

The above command generates the following diagram:



$ mill show visualizePlan foo.compile
[1/1] show
[3/3] visualizePlan

mill show visualizePlan is similar to mill show visualize except that it shows a graph of the entire build plan, including tasks not directly resolved by the query. Tasks directly resolved are shown with a solid border, and dependencies are shown with a dotted border.

The above command generates the following diagram:


Another use case is to view the relationships between modules. For the following two modules:
import mill._, scalalib._

object foo extends ScalaModule {
  def scalaVersion = "2.13.1"

object bar extends ScalaModule {
  def moduleDeps = Seq(foo)

  def scalaVersion = "2.13.1"

mill show visualizePlan _.compile diagrams the relationships between the compile tasks of each module, which illustrates which module depends on which other module’s compilation output:



$ mill clean

clean deletes all the cached outputs of previously executed tasks. It can apply to the entire project, entire modules, or specific tasks.

mill clean                     # clean all outputs
mill clean foo                 # clean all outputs for module 'foo' (including nested modules)
mill clean foo.compile         # only clean outputs for task 'compile' in module 'foo'
mill clean foo.{compile,run}
mill clean "foo.{compile,run}"
mill clean foo.compile
mill clean _.compile
mill clean __.compile

Search for dependency updates

$ mill mill.scalalib.Dependency/showUpdates

Mill can search for updated versions of your project’s dependencies, if available from your project’s configured repositories. Note that it uses heuristics based on common versioning schemes, so it may not work as expected for dependencies with particularly weird version numbers.

Current limitations:

  • Only works for JavaModule modules (including ScalaModules, CrossScalaModules, etc.) and Maven repositories.

  • Always applies to all modules in the build.

  • Doesn’t apply to $ivy dependencies used in the build definition itself.

mill mill.scalalib.Dependency/showUpdates
mill mill.scalalib.Dependency/showUpdates --allowPreRelease true # also show pre-release versions

IDE Support

To support various IDEs and Language Servers, Mill supports the Build Server Protocol in version 2.0.0 and has a built-in BSP server.

In addition to BSP, Mill also supports IntelliJ IDEA project configuration generation directly.

Build Server Protocol (BSP)

To install a BSP connection file .bsp/mill-bsp.json, run:

mill mill.bsp.BSP/install

Working known clients of the BSP server are IntelliJ IDEA and Metals.

You can fine control some BSP server options by specifying command options:



--jobs n

Use n threads in parallel to run tasks. A value of 0 means use as much threads as the system has cpu cores.

When using Metals by default Bloop will be used as your build server unless you explicitly choose Mill. When in a Mill workspace use the "Switch Build Server" command from Metals which will allow you to switch to using Mill as your build server. If no .bsp/mill-bsp.json file exists Metals will automatically create it for you and then connect to Mill.

If you want to use Metals, you may also want to enable SemanticDB support. Without it, some functionality like find references may not work.

We still work on a better and automatic SemanticDB support. Until we have completed it, you can enable SemanticDB manually in your ScalaModule.

For convenience, you can mix-in the mill.scalalib.bsp.ScalaMetalsSupport trait. This enables SemanticDB and also adapts the scalac options to produce more helpful messages in Metals. Mix-in of ScalaMetalsSupport trait
import mill._
import mill.scalalib._
import mill.scalalib.bsp.ScalaMetalsSupport

object foo extends ScalaModule with ScalaMetalsSupport {
  def semanticDbVersion = "4.4.32"
  def scalaVersion = "2.13.8"

IntelliJ Support

To generate IntelliJ IDEA project files into .idea/, run:

mill mill.scalalib.GenIdea/idea

The Build REPL

$ mill --repl
@ foo
res0: foo.type =
    .ideaJavaModuleFacets(ideaConfigVersion: Int)()
    .ideaConfigFiles(ideaConfigVersion: Int)()
    .ivyDepsTree(inverse: Boolean, withCompile: Boolean, withRuntime: Boolean)()
    .runLocal(args: String*)()
    .run(args: String*)()
    .runBackground(args: String*)()
    .runMainBackground(mainClass: String, args: String*)()
    .runMainLocal(mainClass: String, args: String*)()
    .runMain(mainClass: String, args: String*)()
    .repl(replOptions: String*)()

@ foo.compile
res1: mill.package.T[mill.scalalib.api.CompilationResult] = foo.compile(ScalaModule.scala:143)
    Compiles the current module to generate compiled classfiles/bytecode


@ foo.compile()
[25/25] foo.compile
res2: mill.scalalib.api.CompilationResult = CompilationResult(
  PathRef(/Users/lihaoyi/Dropbox/Github/test/out/foo/compile.dest/classes, false, -61934706)

You can run mill --repl to open a build REPL; this is a Scala console with your loaded, which lets you run tasks interactively. The task-running syntax is slightly different from the command-line, but more in line with how you would depend on tasks from within your build file.

You can use this REPL to interactively explore your build to see what is available.

Deploying your code

The two most common things to do once your code is complete is to make an assembly (e.g. for deployment/installation) or publishing (e.g. to Maven Central). Mill comes with both capabilities built in.

Mill comes with the built-in with the ability to make assemblies. Given a simple Mill build:
import mill._, scalalib._

object foo extends ScalaModule {
  def scalaVersion = "2.13.1"

You can make a self-contained assembly via:

$ mill foo.assembly

$ ls -lh out/foo/assembly.dest/out.jar
-rw-r--r--  1 lihaoyi  staff   5.0M Feb 17 11:14 out/foo/assembly.dest/out.jar

You can then move the out.jar file anywhere you would like, and run it standalone using java:

$ java -cp out/foo/assembly.dest/out.jar foo.Example
Hello World!

To publish to Maven Central, you need to make foo also extend Mill’s PublishModule trait:
import mill._, scalalib._, publish._

object foo extends ScalaModule with PublishModule {
  def scalaVersion = "2.13.1"

  def publishVersion = "0.0.1"

  def pomSettings = PomSettings(
    description = "Hello",
    organization = "com.lihaoyi",
    url = "",
    licenses = Seq(License.MIT),
    versionControl = VersionControl.github("lihaoyi", "example"),
    developers = Seq(
      Developer("lihaoyi", "Li Haoyi", "")

You can change the name of the published artifact (artifactId in the Maven POM) by overriding artifactName in the module you want to publish.

You can download an example project with this layout here:

Which you can then publish using the mill foo.publish command, which takes your sonatype credentials ( e.g. lihaoyi:foobarbaz) and GPG password as inputs:

$ mill foo.publish
Missing arguments: (--sonatypeCreds: String, --release: Boolean)

Arguments provided did not match expected signature:

  --sonatypeCreds   String (format: "username:password")
  --signed          Boolean (default true)
  --gpgArgs         Seq[String] (default Seq("--batch", "--yes", "-a", "-b"))
  --readTimeout     Int (default 60000)
  --release         Boolean (default true)
  --connectTimeout  Int (default 5000)
  --awaitTimeout    Int (default 120000)
  --stagingRelease  Boolean (default true)

You also need to specify release as true or false, depending on whether you just want to stage your module on or you want Mill to complete the release process to Maven Central.

If you are publishing multiple artifacts, you can also use mill mill.scalalib.PublishModule/publishAll as described

Structure of the out/ folder

The out/ folder contains all the generated files & metadata for your build. It is structured with one folder per Target/Command, that is run, e.g.:

  • out/core/compile/

  • out/main/test/compile/

  • out/main/test/forkTest/

  • out/scalalib/compile/

There are also top-level build-related files in the out/ folder, prefixed as mill-*. The most useful is mill-profile.json, which logs the tasks run and time taken for the last Mill command you executed. This is very useful if you want to find out exactly what tasks are being run and Mill is being slow.

Each task currently creates contains the following files:

  • foo.dest/: optional, a path for the Task to use either as a scratch space, or to place generated files that are returned using PathRef references. A Task should only output files within its own given dest/ folder (available as T.dest) to avoid conflicting with another Task, but can name files within dest/ arbitrarily.

  • foo.log: optional, the stdout/stderr of the Task. This is also streamed to the console during evaluation.

  • foo.json: the cache-key and JSON-serialized return-value of the Target/Command. The return-value can also be retrieved via mill show foo.compile. Binary blobs are typically not included in foo.json, and instead stored as separate binary files in dest/ which are then referenced by foo.json via PathRef references.

The out/ folder is intentionally kept simple and user-readable. If your build is not behaving as you would expect, feel free to poke around the various foo.dest/ folders to see what files are being created, or the foo.json files to see what is being returned by a particular task. You can also simply delete folders within out/ if you want to force portions of your project to be rebuilt, e.g. by deleting the out/main/ or out/main/test/compile/ folders.

Overriding Mill Versions

Apart from downloading and installing new versions of Mill globally, there are a few ways of selecting/updating your Mill version:

  • Create a .mill-version file to specify the version of Mill you wish to use:

echo "0.5.0" > .mill-version

.mill-version takes precedence over the version of Mill specified in the ./mill script.

  • Pass in a MILL_VERSION environment variable, e.g.

MILL_VERSION=0.5.0-3-4faefb mill __.compile


MILL_VERSION=0.5.0-3-4faefb ./mill __.compile

to override the Mill version manually. This takes precedence over the version specified in ./mill or .mill-version

Note that both of these overrides only work for versions 0.5.0 and above.

Automatic Mill updates

If your project is hosted on GitHub, GitLab, or Bitbucket, you can use Scala Steward to automatically open a pull request to update your Mill version (in .mill-version file), whenever there is a newer version available.

Scala Steward can also scan your project dependencies and keep them up-to-date.

Development Releases

In case you want to try out the latest features and improvements that are currently in the main branch, unstable versions of Mill are available as binaries named #.#.#-n-hash linked to the latest tag. Installing the latest unstable release is recommended for bootstrapping mill.

The easiest way to use a development release is by updating the Bootstrap Scripts (Linux/OS-X Only), or Overriding Mill Versions via an environment variable or .mill-version file.

Running Mill with custom JVM options

It’s possible to pass JVM options to the Mill launcher. To do this you need to create a .mill-jvm-opts file in your project’s root. This file should contain JVM options (strings, starting with -X), one per line. All other lines will be ignored.

For example, if your build requires a lot of memory and bigger stack size, your .mill-jvm-opts could look like this:


The file name for passing JVM options to the Mill launcher is configurable. If for some reason you don’t want to use .mill-jvm-opts file name, add MILL_JVM_OPTS_PATH environment variable with any other file name.

Come by our Gitter Channel if you want to ask questions or say hi!