Installation & IDE Support

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

Although the Mill example projects come with their own ./mill bootstrap script, you can also download it manually:

curl -L https://github.com/com-lihaoyi/mill/releases/download/0.12.2/0.12.2 > mill && chmod +x mill
echo 0.12.2 > .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.

Windows

If you are running on Windows, you should use lefou/millw as a drop-in replacement for ./mill that supports running on all major platforms including MS Windows.

./millw will likely be merged into ./mill in the near future.

IDE Support

Mill supports IntelliJ and VSCode, both via the standard Build Server Protocol

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

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 should use IntelliJ

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

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

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

The idea is to set an environment variable COURSIER_REPOSITORIES (see coursier docs). 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 etc.

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.

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 or .config/mill-version file.