Installation and IDE Support

The best method of installing Mill is to just install a bootstrap script. This script can determine the best version to be used by a project (e.g. by reading a .mill-version file) and will use this exact Mill version. If that version is not installed locally, it will be downloaded automatically.

Bootstrap Scripts

There are currently two bootstrap script available, one in the Mill repository, which only work for Linux and Unix-like machines, and one external millw script, with more features and also Windows support.

Using millw is recommended.

We plan to merge both script in the future.

Mill’s Bootstrap Script (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 https://github.com/com-lihaoyi/mill/releases/download/0.11.0/0.11.0-7-9cdfc9 > 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. 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.

In general, bootstrap scripts are the recommended way of installing Mill because they reduce the chance of errors due to the installed version of Mill being incompatible with the version expected by your build.

millw

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.

Installing Mill Globally

While the Bootstrap Scripts approach above is the recommended way of installing Mill for a project, you can also install Mill globally in your operating system using the commands shown below.

OS X

Installation via homebrew:

brew install mill

Arch Linux

Arch Linux has a Community 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, --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

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.11.0/0.11.0 > ~/.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.

IDE Support

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

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

Build Server Protocol (BSP)

The Build Server Protocol has the concept of BSP server discovery, which means: A BSP client can connect to any BSP server, as long as there is a connection file under the .bsp/ directory.

To install a BSP connection file .bsp/mill-bsp.json for Mill, 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:

Option

Description

--jobs n

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

Using Metals

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.

Metals is relying on SemanticDB to enable many of its features. Mill BSP now also supports to provide this SemanticDB data, when the BSP client (like Metals) requests it.

As of writing this, Metals 0.11.8 is the latest available version, which is not able to detect the fact, that Mill is already providing SemanticDB data. As a consequence, it reports missing SemanticDB data, although some SemanticDB-based features are already working. This may be fixed eventually in a future release of Metals.

Updating older setups

In the past, we provided SemanticDB support via mill.scalalib.bsp.ScalaMetalsSupport trait, which had to be mixed-in to your Scala modules. This is no longer needed and deprecated. You should remove these mix-ins. ScalaMetalsSupport trait is now deprecated and will be removed in the future.

If things go wrong

In case things go wrong, it can be sometimes hard to find the cause. BSP is just a protocol, and as such, issues on the server side (the Mill BSP server) might not well propagated to the BSP client (your IDE).

For that reason Mill BSP server is writing a log file under .bsp/mill-bsp.stderr, where you can find various information about what’s going on. Its content should look familiar, as it contains regular Mill output accompanied by additional BSP client-server communication details.

You can increase the verbosity of that log file, when you run Mill with --debug at installation time (of the BSP discovery file).

mill --debug mill.bsp.BSP/install

Using Bloop (standalone BSP server)

If you wish to use Bloop as your build server (it is the default metals BSP implementation) with metals / vscode, consider using the mill bloop plugin.

Bloop Plugin

This is preferred to the instructions (currently) on the bloop website.

Please be aware, that the Bloop contrib plugin is maintained by the community and is probably not on a par with the built-in BSP server.

IntelliJ IDEA Support

IntelliJ IDEA also supports the BSP protocol. To use this support, just follow the directions in Build Server Protocol (BSP).

Additionally, you can generate IDEA project files directly with Mill. This is probably the preferred way if you work on polyglot projects and need support for other languages like Kotlin or AspectJ, which are currently not specifically configured over BSP.

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

mill mill.scalalib.GenIdea/idea

Updating Mill

If you have installed Mill via the recommended Bootstrap Script method, you don’t need to install multiple version of Mill explicitly.

Follow the next Overriding Mill Versions section for details.

Overriding Mill Versions

Apart from downloading and installing new versions of Mill globally, there are a few ways of selecting/updating your Mill version. This will only work, if you have choosen one of the Boostrap script methods:

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

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.

The easiest way to use a development release is to use one of the Bootstrap Scripts, which support Overriding Mill Versions via an MILL_VERSION environment variable or a .mill-version file.