Installation & IDE Setup

The standard method of installing Mill is to install a ./mill bootstrap script, similar to ./gradlew or ./mvnw in other build tools. This script can determine the best version to be used by a project (e.g. by reading a .mill-version) and will use this exact Mill version. If the determined Mill version is not installed locally, it will be downloaded automatically.

For all the examples in this documentation, there is a download link that provides a zip file containing the full example ready to use. These examples come with a ./mill script you can use to immediately begin working with the project, needing only a JVM installed globally.

Bootstrap Scripts

The Mill example projects in this documentation come with ./mill and ./mill.bat bootstrap script, included. You can also download the boostrap script manually:

# Mac/Linux
curl -L https://repo1.maven.org/maven2/com/lihaoyi/mill-dist/0.13.0-M0/mill -o mill
chmod +x mill
echo 0.12.8 > .mill-version

# Windows
curl -L https://repo1.maven.org/maven2/com/lihaoyi/mill-dist/0.13.0-M0/mill.bat -o mill.bat
echo 0.12.8 > .mill-version

Downloading a mill bootstrap script to the root of your project repository helps make it easier for new contributors to build your project, as they don’t have to install Mill before they can start. Anyone who wants to work with the project can simply use the ./mill script directly.

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

In general, bootstrap scripts are the recommended way of installing Mill. Similar to ./gradlew or ./mvnw, the ./mill bootstrap script reduces the chance of errors due to the installed version of Mill being incompatible with the version expected by your build. In-project bootstrap scripts are also useful for running Mill in CI/CD, ensuring that your build server like Jenkins or Github Actions has the correct version of Mill present to build, compile or test your code.

If you are starting a new project using a Mill bootstrap script, you can use the mill init to initialize the project folder with one of the Mill example projects. There are a wide range of example projects, from hello-world to multi-module libraries to client-server web applications, and you can pick one most similar to what you are doing so you can hit the ground running working.

Mill Native Executable

The default Mill executable configured above requires a JVM (11 or above) installed globally in order to run, and imposes some Java startup overhead (100-200ms) when running Mill from the command line. You can also use Mill’s native executables by appending a -native suffix to the Mill version:

echo 0.12.8-native > .mill-version

Using the -native suffix should provide a faster CLI experience than using Mill’s default JVM launcher, and makes it easier to install Mill in environments without a JVM pre-installed.

Mill native executables are supported on the following OS/CPU combinations:

Windows

Mac

Linux

Intel

Y

Y

Y

ARM

Y

Y

Notably, Mill native executables do not support Windows-ARM, due to limitations in the upstream Graal Native Image tooling (see oracle/graal#9215). If you are on a platform not supported by Mill’s native executables, use the default JVM launcher instead.

Customizing Mill’s JVM

Mill allows you to specify the exact JVM version you want to use to run the build tool via a .mill-jvm-version file such as:

echo temurin:17.0.6 > .mill-jvm-version

This has two benefits

  • .mill-jvm-version can also be used with Mill’s default JVM launcher if you want your Mill process to use a different JVM than what you have installed globally. This can help ensure your project uses a consistent JVM version and behaves identically regardless of what the developer may have installed on their laptop or dev environment

  • .mill-jvm-version can be used together with Mill Native Executables to build your project without needing a JVM pre-installed at all. This simplifies project setup and onboarding of new developers.

IDE Support

Mill supports IntelliJ and VSCode and in general any client of the standard Build Server Protocol (BSP).

Your IDEs may already auto-detect the Mill project and run this command on behalf of you, when opening/importing the project.

IntelliJ

To use Mill with IntelliJ, first ensure you have the free IntelliJ Scala Plugin installed. This is necessary as Mill build files are written in Scala, even if you are using it to build a Java or Kotlin or Python project.

Once you have the plugin installed, you can use IntelliJ to open any project containing a Mill build.mill file, and IntelliJ will automatically load the Mill build. If you have multiple build systems installed, Intellij may give you choice which build system configuration to use for the import, which case select BSP:

IntellijSelectBsp

This will provide support both for your application code, as well as the code in the build.mill:

IntellijApp
IntellijBuild

If IntelliJ does not highlight the .mill files correctly, you can explicitly enable it by adding *.mill to the Scala file type:

IntellijFileTypeConfig

If you make changes to your Mill build.mill, you can ask Intellij to load those updates by opening the "BSP" tab and clicking the "Refresh" button

IntellijRefresh

To prepare your project for IDEs, and in general any BSP client, you can also run this command to generate the BSP configuration files:

./mill mill.bsp.BSP/install

IntelliJ IDEA XML Support

Apart from using the Build Server Protocol, you can also generate IDEA project files directly with Mill. This is probably the preferred way if you work on polyglot projects and need support for frameworks like AspectJ, which are currently not specifically configured over BSP.

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

./mill mill.idea.GenIdea/

This will generate the XML files IntelliJ uses to configure your project

.idea
.idea/scala_settings.xml
.idea/mill_modules
.idea/mill_modules/.iml
.idea/mill_modules/mill-build.iml
.idea/mill_modules/test.iml
.idea/libraries
.idea/libraries/mill_scalalib_2_13_0_11_10_jar.xml
...
.idea/workspace.xml
.idea/modules.xml
.idea/scala_compiler.xml
.idea/misc.xml

After the files are generated, you can open the folder in IntelliJ to load the project into your IDE. If you make changes to your Mill build.mill, you can update the project config those updates by running ./mill mill.idea.GenIdea/ again.

VSCode

To use Mill with VSCode, first ensure you have the free Metals VSCode Scala language server installed. This is necessary as Mill build files are written in Scala, even if you are using it to build a Java project.

Mill in VSCode only supports Java and Scala. Kotlin users are advised to use the free IntelliJ IDEA Community Edition

Once you have the language server installed, you can ask VSCode to open any folder containing a Mill build.mill file, and VSCode will ask you to import your Mill build. This will provide support both for your application code, as well as the code in the build.mill:

VSCodeApp
VSCodeBuild

If you make changes to your Mill build.mill, you can ask VSCode to load those updates by opening the "BSP" tab and clicking the "Refresh" button

VSCodeRefresh

Other Editors / Metals

A lot of other editors may work too, since Metals, the Language Server for Scala has built-in support for BSP. See the general instructions above.

Debugging IDE issues

Mill’s BSP IDE integration writes to a log file under .bsp/mill-bsp.stderr, where you can find various information about what’s going on. It contains regular Mill output accompanied by additional BSP client-server communication details. This can be useful to look at if your IDE fails to import your Mill project

Updating Mill

Typically, most Mill projects use a .mill-version file to configure what version to use. You can update the version specified in this file in order to change the version of Mill. The file path .config/mill-version is also supported. If neither is provided, the ./mill bootstrap script will use the DEFAULT_MILL_VERSION it has built in.

To choose a different Mill version on an ad-hoc basis, e.g. for experimentation, you can pass in a MILL_VERSION environment variable, e.g.

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

or

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

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

Using Mill without access to Maven Central

Under some circumstances (e.g. corporate firewalls), you may not have access maven central. The typical symptom will be error messages which look like this;

1 tasks failed
mill.scalalib.ZincWorkerModule.classpath
Resolution failed for 1 modules:
--------------------------------------------
  com.lihaoyi:mill-scalalib-worker_2.13:0.11.1
        not found: C:\Users\partens\.ivy2\local\com.lihaoyi\mill-scalalib-worker_2.13\0.11.1\ivys\ivy.xml
        download error: Caught java.io.IOException (Server returned HTTP response code: 503 for URL: https://repo1.maven.org/maven2/com/lihaoyi/mill-scalalib-worker_2.13/0.11.1/mill-scalalib-worker_2.13-0.11.1.pom) while downloading https://repo1.maven.org/maven2/com/lihaoyi/mill-scalalib-worker_2.13/0.11.1/mill-scalalib-worker_2.13-0.11.1.pom

It is expected that basic commands (e.g. clean) will not work, as Mill saying it is unable to resolve it’s own, fundamental, dependencies from the default Maven Central JVM package repository. Under such circumstances, you will normally have access to some proxy, or other corporate repository which resolves maven artifacts. The strategy is simply to tell mill to use that instead.

To resolve this, you can set an environment variable COURSIER_REPOSITORIES (see coursier docs) to point at your own server that mirrors the Maven Central artifacts. The below command should pass the environment variable to the mill command.

COURSIER_REPOSITORIES=https://packages.corp.com/artifactory/maven/ mill resolve _

If you are using bootstrap script, a more permanent solution could be to set the environment variable at the top of the bootstrap script, or as a user environment variable.

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 or .config/mill-version file), whenever there is a newer version available.

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

Unstable 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 versions named:

  • {stable-version}-{commits-since-stable-version}-{commit-hash}

For example, 0.12.5-193-b4d975 is an unstable release after 0.12.5, with 193 additional commits, on commit hash b4d975.

The list of unstable releases can be seen on Maven Central:

Or find the latest unstable version here:

You can update your .mill-version to to the unstable version and the bootstrap script will download it for you to try it out in your project.

Other installation methods

The installation methods listed below are maintained outside of Mill and may not have the same features as the bootstrap scripts. You can try using them, but the officially supported way to use Mill is via the bootstrap script above, so the Mill maintainers may be unable to help you if you have issues with some alternate installation method.
Some of the installations via package managers install a fixed version of Mill and do not support project-specific selection of the preferred Mill version. If you want to use the MILL_VERSION environment variable or need support for .mill-version or .config/mill-version files to control the actual used Mill version, please use a bootstrap script instead.

OS X

Installation via homebrew:

brew install mill

Arch Linux

Arch Linux has an Extra package for mill:

pacman -S mill

FreeBSD

Installation via pkg(8):

pkg install mill

Gentoo Linux

emerge dev-java/mill-bin

Windows

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

WSL / MSYS2 / Cycgin / Git-Bash

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. Note that:

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

  • 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

Docker

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

Manual

To get started, download Mill and install it into your HOME ".local/bin" via the following curl/chmod command:

sh -c "curl -L https://github.com/com-lihaoyi/mill/releases/download/0.12.8/0.12.8 > ~/.local/bin/mill && chmod +x ~/.local/bin/mill"

Coursier (unsupported)

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

Asdf (unsupported)

You can install and manage Mill via the Multiple Runtime Version Manager - asdf.

Support by asdf is currently possible by using the asdf-mill plugin:

Steps to install the mill plugin and Mill with asdf
---
asdf plugin add mill
asdf install mill latest
asdf global mill latest
---