Maven: Configuring Maven

The launcher script looks for .mvn starting in the current directory and moving up through the parents, until it finds one. Running a command inside a module therefore still uses the .mvn of the multi-module root. With -f, the lookup starts from the POM that is named:

In both cases the value config comes from the root .mvn/maven.config. The five version lines are there because that file contains -V (see below), not because of the -q of the helper. Maven 3.9.16 and 4.0.0-rc-7 found the file in the same two situations (the value was config in all three; the version lines are not repeated). Maven 4 also uses the directory as the marker of the project root; without one it prints the warning described on Getting Started.

Source: Maven: Configuring Apache Maven, .mvn directory

maven.config holds command-line arguments that are added to every run. The official page gives -T3 -U --fail-at-end as an example. Since Maven 3.9.0 each argument goes on a line of its own, and lines that begin with # are comments; Maven 3.8.x and older did not support comments (not run here, there is no such Maven on this machine). A file that uses an option together with its value must also keep them on separate lines when the option takes a separate value. Here is the file that the run in the previous section read:

-B is batch mode, -V prints the version first, and -T followed by 2 on the next line is the same as -T 2: two build threads. Running without -q shows all three at work. Only lines that the grep below removes (the plugin prefix lookups, which differ on a cold local repository) were left out; the output is from Maven 3.10.0:

The "thread count of 2" line is the proof that -T, 2 was read as an option and its value. Maven 3.9.16 and 4.0.0-rc-7 printed the same thread count line. Typical contents of a maven.config are --no-transfer-progress, --fail-at-end, a -T, and the properties of a CI-friendly build (-Drevision=..., see CI-Friendly Versions). Keep it free of anything personal: a profile that only one developer needs is better activated by that developer in the shell.

Source: Maven: Configuring Apache Maven, .mvn/maven.config file

The three sources of arguments are applied in a fixed order, and for a property that is set more than once the one applied last wins. A property set in all three places:

The order is .mvn/maven.config, then MAVEN_ARGS, then the command line, so the project supplies defaults, the environment adjusts them, and what is typed has the last word. The output was identical on Maven 3.9.16, 3.10.0 and 4.0.0-rc-7. A .mavenrc that exports MAVEN_ARGS, as above, takes part as the environment, which is why mavenrc beat config in the previous section.

Source: Maven: Configuring Apache Maven, MAVEN_ARGS environment variable

jvm.config holds JVM options for Maven, one or more per line, and is the project-level counterpart of MAVEN_OPTS. The official page says it makes MAVEN_OPTS and .mavenrc unnecessary for per-project settings: the file is committed, and everybody gets the same heap and the same system properties without configuring a shell. This file sets a heap and a property, and asks the JVM to print its flags:

The grep keeps the heap line and the value of base.dir. Results by version:

Expanding MAVEN_PROJECTBASEDIR inside jvm.config is listed in the Maven 3.10.0 release notes. It is useful to point an option at a file kept in the repository, such as -Djava.util.logging.config.file=... or a truststore.

Two further differences between Maven 3 and Maven 4 showed up in the same experiments. The first is the order in which jvm.config and MAVEN_OPTS are combined. When two options conflict, the JVM keeps the last one. The launcher script of Maven 3.9.16 and 3.10.0 builds the options as the contents of jvm.config followed by MAVEN_OPTS (line 214 of the 3.10.0 script); the script of Maven 4.0.0-rc-7 appends the contents of jvm.config after MAVEN_OPTS. With -Xmx300m in the file and MAVEN_OPTS=-Xmx512m:

In Maven 3 the person running the build can therefore override the project; in Maven 4 the project can force its value. Check this if a build is moved between the two.

The second difference is quoting. Maven 3 splits jvm.config into words with the shell, and a quotation mark is not interpreted. An option that contains a space and is written with quotes made the JVM fail to start. The file contained one line, -Dwith.space="a b":

That is the output of Maven 3.9.16 and 3.10.0. Maven 4.0.0-rc-7, whose distribution contains a Java helper for reading the file (bin/JvmConfigParser.java), printed a b. A Maven 3 file should avoid values with spaces.

The example in the official page is -Xmx2048m -Xms1024m -XX:MaxPermSize=512m -Djava.awt.headless=true. It is out of date. The MaxPermSize option was removed together with the permanent generation in Java 8, and a modern JVM refuses to start with it. This is what a file containing exactly that line did on Maven 3.10.0 with JDK 26:

Use only the heap options of that line (and -Djava.awt.headless=true, which is still valid).

Source: Maven: Configuring Apache Maven, .mvn/jvm.config file

Source: Maven 3.10.0 release notes

A core extension is a library that is loaded into Maven itself, before the build starts, and can replace or add components: for example the Build Cache extension, a Develocity extension, or a custom lifecycle. It is different from a build extension declared inside a POM (<build><extensions>), which is only known after the POM has been read. The page Extensions covers what extensions can do and how they are written; this section is only about where they are declared.

Until Maven 3.2.5 an extension had to be copied by hand into lib/ext of the installation, which meant changing every developer’s Maven. The mechanism of .mvn/extensions.xml replaced that. The file lists Maven coordinates, with the same groupId, artifactId and version as any dependency, and Maven downloads the extension and its transitive dependencies. The following file loads the Build Cache extension, version 1.3.0:

Running Maven 3.10.0 in the project, the extension announces itself before Maven starts scanning for projects. The grep keeps only the extension’s own lines, and the path was shortened:

(The extension then also reports that caching is disabled for the parent project, because it has packaging pom.) The cache itself is the subject of Build Performance: Cache, Parallel Builds & mvnd.

Before Maven 3.10 only the project could declare core extensions this way. The Maven 3.10.0 release notes add "support for user-wide extensions (in ~/.m2/extensions.xml) and installation-wide extensions (in $MAVEN_HOME/conf/extensions.xml)", in addition to the project’s. The same extension file was placed in each of the three locations (for the user one, the home directory was redirected with -Duser.home, see the next section) and the "Using XX hash" line of the extension was counted:

For the installation-wide file a copy of each distribution was used, so that the real installation was not modified. The installation-wide location was not run on Maven 4.0.0-rc-7, but the configuration table in the next section lists maven.installation.extensions as ${maven.installation.conf}/extensions.xml and maven.user.extensions as ${maven.user.conf}/extensions.xml.

User-wide and installation-wide extensions apply to every build of the machine, including builds of projects that never heard of them, so they suit tools that observe or accelerate (a build scanner, a mirror selector) rather than ones that change the output. A project that needs a core extension to build correctly should declare it itself, in .mvn/extensions.xml.

Source: Maven: Configuring Apache Maven, .mvn/extensions.xml file

Source: Maven: core-extensions-1.1.0.xsd

Source: Maven 3.10.0 release notes

Maven 4 reads the same three files and gives the directory a more formal definition. The conf/maven-system.properties file of the 4.0.0-rc-7 distribution defines three directories and the files inside them:

On top of these, the settings, toolchains and extensions files exist at three levels (maven.installation.settings, maven.user.settings, maven.project.settings, and the same for toolchains and extensions), so .mvn/settings.xml is a project-level settings file in Maven 4 (not run here). Properties can also be set from files rather than the command line: conf/maven-user.properties of the distribution includes, when they exist, ${maven.user.conf}/maven-user.properties, maven.properties in the same directory, and the two names in .mvn. A file .mvn/maven-user.properties with the line who=userprops made Maven 4.0.0-rc-7 print:

and Maven 3.10.0, on the same project, printed null object or invalid expression. The distribution’s own comment says that maven.properties "will be removed in Maven 4.1.0" and only maven-user.properties will be loaded, so use that name. These properties are user properties, the same as -D ones.

Source: Maven 4.0.0-rc-7: Maven Configuration Options

The official guide puts <localRepository> in the user’s settings.xml, and adds that the path "must be an absolute path":

To prove the setting is read, the run redirected the JVM’s notion of the home directory with -Duser.home (set in MAVEN_OPTS) to the scratch home, whose .m2/settings.xml contains <localRepository> pointing at <lab>/home/shared-repo. Setting HOME, as for .mavenrc, would not have been enough: Java does not take user.home from that variable on this system.

Source: Maven guide: Configuring your Local Repository

The system property maven.repo.local overrides the setting, and, because it is a property, it can be set in maven.config or MAVEN_ARGS:

The next run put a relative path in .mvn/maven.config, a common way to give a project its own local repository (-Dmaven.repo.local=.mvn/local-repo). The path is resolved against the directory the command is run from, not against the directory of .mvn:

That is Maven 3.10.0; 3.9.16 and 4.0.0-rc-7 gave the first line when run from the root. Running inside the module created a second repository under app. Prefer an absolute path, and remember that a per-project repository downloads everything again, once for each project.

Source: Maven 4.0.0-rc-7: Maven Configuration Options

Since Maven 3.9.0 a read-only "tail" of one or more repositories can be consulted before Maven goes to the network, while writes go to the main local repository. This is how a CI image can ship a pre-populated cache and still run each job with a clean, disposable repository. The experiment counted the artifacts downloaded by the same Help plugin run into a new, empty local repository, once without and once with the existing ~/.m2/repository as the tail (Maven 3.10.0):

(The two lines were obtained by counting the "Downloaded from" lines of Maven’s output; the three downloads of the second run were metadata files for the plugin lookup.) The other keys of the family, from the Maven configuration table, are maven.repo.local.tail.ignoreAvailability (default true), maven.repo.local.head (Maven 4.0.0: prepends instead of appends) and maven.repo.local.recordReverseTree (3.9.0, false by default), which, when true, records in the local repository why an artifact is there. That last key was tried here, and no .tracking directory appeared for the Help plugin run; it is a diagnostic for a build with dependencies, and it is not demonstrated.

Source: Maven 4.0.0-rc-7: Maven Configuration Options

Repositories to download from, mirrors and the layout of the local repository are on Repositories, Mirrors & Repository Managers.

The configuring guide notes that by default Maven downloads up to five artifacts at once, and that -Dmaven.artifact.threads=1 reduces it, permanently through MAVEN_OPTS (for example export MAVEN_OPTS=-Dmaven.artifact.threads=3). That text was written for the old resolver; the property name was not checked against Maven 3.10.0’s resolver, and no run was made (not run here). The reactor’s own parallelism is a different thing and is controlled with -T, which belongs in maven.config.

Source: Maven guide: Configuring your Local Repository

Source: Maven 4.0.0-rc-7: Maven Configuration Options