toolchains.xml

Where Maven reads toolchains.xml, the elements of a JDK toolchain, how a requirement matches an entry, and which plugins use the selected toolchain.

toolchains.xml describes the tools installed on a machine, most often JDKs, so that a build can ask for one without naming its path. Toolchains and the JDK Maven runs on explains the idea; Build with a different JDK than Maven runs on puts it to use.

Where Maven reads it

Maven reads two files and puts their toolchains in one list, those of the user file first.

A file in a default location that does not exist is skipped. A file named with -t or -gt must exist, or Maven stops with The specified user toolchains file does not exist or The specified global toolchains file does not exist. The global file that comes with Maven contains only comments, so out of the box all toolchains come from the user file.

Maven 4: The global file is called the installation file. Its option is -it or --install-toolchains, and its property maven.installation.toolchains. -gt still works, with a warning that it is deprecated. A missing file named with either option stops Maven with The specified installation toolchains file does not exist.

Elements

~/.m2/toolchains.xml

<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>17</version>
      <vendor>temurin</vendor>
    </provides>
    <configuration>
      <jdkHome>/opt/jdk/temurin-17</jdkHome>
    </configuration>
  </toolchain>
</toolchains>

The root element may carry the namespace http://maven.apache.org/TOOLCHAINS/1.1.0, which Maven 3 uses, or http://maven.apache.org/TOOLCHAINS/1.2.0, which Maven 4 uses, or none. Maven 3.9, 3.10 and 4.0 read all three forms.

How requirements match

A requirement is the set of labels a project asks for, in the configuration of the toolchains plugin or in a plugin's jdkToolchain parameter:

pom.xml

<toolchains>
  <jdk>
    <version>[11,18)</version>
    <vendor>temurin</vendor>
  </jdk>
</toolchains>

• The element name, here jdk, is the toolchain type.
• Every label in the requirement must match the label of the same name in <provides>. Labels the requirement does not mention are not checked.
• version is compared as a version. A single version matches only the same version: 17 matches 17, but not 17.0.20, and 8 does not match 1.8. A range, such as [17,18), [11,) or (,11], matches every version inside it: [17,18) matches 17 and 17.0.20, and [1.8,9) matches 1.8.
• Every other label is compared as text, ignoring case: Temurin matches temurin.
• When several toolchains match, the first one in the list is used: the user file before the global file, and within a file from top to bottom.

When no toolchain matches, the toolchains plugin stops the build:

[ERROR] No toolchain matched from 3 found for type jdk
[ERROR] Cannot find matching toolchain definitions for the following toolchain types:
jdk [ version='25' ]

Discovered JDK toolchains

The select-jdk-toolchain goal of the maven-toolchains-plugin, since version 3.2.0, matches its requirement against the entries of toolchains.xml and against the JDKs it discovers. It finds JDKs through:

• the environment variables JAVA_HOME and JAVA<n>_HOME, such as JAVA17_HOME;
• the JDK Maven runs on;
• the directories of installers in your home directory: .sdkman/candidates/java, .jdks, .m2/jdks, .gradle/jdks, .jenv/versions, .jbang/cache/jdks, .asdf/installs/java, .jabba/jdk, .local/share/mise/installs/java;
• on macOS, /Library/Java/JavaVirtualMachines and ~/Library/Java/JavaVirtualMachines;
• on Windows, the directories of Amazon Corretto, BellSoft, Eclipse Adoptium, Java and Zulu under C:\Program Files, and the JDKs installed with Scoop;
• on other systems, /usr/jdk, /usr/java, /usr/local/java, /opt/java, /usr/lib/jvm and /usr/lib64/jvm;
• the tool cache of GitHub Actions runners.

A directory without bin/javac is skipped. The goal keeps what it found in ~/.m2/discovered-jdk-toolchains-cache.xml.

A discovered JDK provides these labels, read from the JDK itself:

The goal takes its requirement from these parameters:

The plugin's JDK discovery page and the description of the goal have the details. The goals display-discovered-jdk-toolchains and generate-jdk-toolchains-xml print the discovered JDKs, the second one in the format of toolchains.xml.

Plugins that use toolchains

These plugins use the JDK toolchain selected for the module. The plugins with a version in the last column also accept a requirement of their own in a jdkToolchain parameter, which overrides the module's selection for that plugin and is matched against toolchains.xml only.

The protobuf-maven-plugin of org.xolstice uses a toolchain of type protobuf for the protoc compiler, since version 0.5.0. A plugin can define its own toolchain type; see Custom Toolchains.