Updated April 9, 2023

Maven Settings.XML

Maven settings.xml serves as a settings file for configurations involved in maven execution. Maven automates the entire process of project build, reporting, and documentation, thus drastically reducing human errors. It is used majorly in Java-based projects. The settings file allows configuring server credentials, proxy configurations, and maven profiles. The settings configuration also includes the locations of local and remote repositories.

Key Takeaways

Maven settings.xml serves as a settings file for configurations involved in maven execution.
The xmlcontains system or user configurations that are not specific to the project.
The settings file contains nine possible child elements to define values for the configuration. It includes configuring server credentials, proxy configurations, and maven profiles.

Overview

Maven is a powerful project management tool based on the concept of POM (project object model).
The xml is a single configuration file that describes the major project information, manages dependencies, and configures plugins for building the application. The configuration here is static, no matter who is building it.
Like the XML, the settings file settings.xml also contains configurations. However, they are based on the current environment and not project-specific.
It includes elements to define values that configure the maven execution, like the locations of local and alternate remote repositories.
We can also specify values we don’t want in the source code, like the authentication information. In the absence of the file, Maven applies the default settings.

Where can I find Maven settings.xml?

The following directories can have the setting.xml file:

Maven installation directory or global settings: ${maven.home}/conf/settings.xml
User home directory or user-level settings: ${user.home}/.m2/settings.xml
Maven either uses one or both of the above settings files. If both files are present, they are combined primarily considering user xml.
We can also override the locations of both settings from the command line. E.g. The command to set global settings in c:\global\settings.xml

$ mvn clean --global-settings c:\ global\settings.xml

How to Use Maven Settings.xml?

You can use Maven’s default settings.xml to specify your configurations.
The default file contains explanations and examples of its nine possible child elements.
Hence it is easy to modify the settings.xml according to your requirements.
For interpolation of contents of the settings.xml, use ${user.home} for all other system properties, and for the environment variables, use the expression like ${env.HOME}.
The interpolation cannot include the properties within the profiles of the settings.xml.

Configurations of Maven Settings.XML

An outline of the settings.xml:

<settings xmlns=http://maven.apache.org/SETTINGS/1.0.0 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
<localRepository/>
<interactiveMode/>
<offline/>
<pluginGroups/>
<servers/>
<mirrors/>
<proxies/>
<profiles/>
<activeProfiles/>
</settings>

Simple values of Maven Settings.XML

settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
<localRepository>${user.home}/.m2/repository</localRepository>
<interactiveMode>true</interactiveMode>
<offline>false</offline>
......
</settings

The top-level elements in the settings broadly include simple values that correspond to characterize the active aspects of the Maven.
LocalRepository: It specifies the location of the local repository where the artifacts are to be stored. Here the default value points to the user’s home directory. It is highly beneficial for the main build server as it allows all logged-in users to build from a shared local repository.
InteractiveMode: This determines whether Maven interacts with the user when it needs input. The default is true. If false, we cannot interact with the prompt, and Maven fetches values from other relevant settings.
Offline: It decides whether Maven operates offline. The element defaults to false. It impacts artifact download, deployment, etc.

Plugin Groups

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
……
<pluginGroups>
<pluginGroup>com.your.plugins</pluginGroup>
</pluginGroups>
......
</settings>

The pluginGroup contains a list of additional group identifiers.
The list helps when a plugin is used without specifying the groupId in the command line.
The default values in the list are apache.maven.pluginsand org.codehaus.mojo.

Servers

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
……
<servers>
<server>
<id>depo repository</id>
<username>user</username>
<password>password</password>
<privateKey>private-key-path</privateKey>
<passphrase> passphrase</passphrase>
<filePermissions>664</filePermissions>
<directoryPermissions>775</directoryPermissions>
<configuration></configuration>
</server>
</servers>
……
</settings>

Maven requires authentication profiles to interact with other servers. With server-id as the key, this element lets you specify the security credentials needed to connect those servers.
id: This is the server’s server-id used within the system that Maven is trying to connect.
username, password: It denotes the username and password credentials for authentication.
privateKey, passphrase: It signifies the path to a private key and a passphrase.
You should either use username/password or privateKey/passphrase.
filePermissions, directoryPermissions: It specifies the permissions required on the deployment of the repository or directory. It is a three-digit legal value that matches the *nix file permissions.

Mirror

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
…..
<mirrors>
<mirror>
<id>uniqueid</id>
<name>user-friendly name</name>
<url> http://mrepository.com/repo/path</url>
<mirrorOf>mrepo1</mirrorOf>
</mirror>
</mirrors>
……
</settings>

It is a list of mirrors that act as an alternate location for your repository.
When the intended repository from the xml faces troublesome situations like heavy traffic, we can mirror it to several locations.
id: It is a unique id referring to the mirroring repository.
name: It is a readable name for this mirror.
url: Maven will use this URL to connect to the alternate repository instead of the original.
mirrorOf: The ID of the repository the mirror serves, which corresponds to this mirror’s mirrorOf element. It is not the same as the mirror id.

Proxies

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
…..
<proxies>
<proxy>
<id>proxyid</id>
<active>true</active>
<protocol>http</protocol>
<host>user.proxy.com </host>
<port>80</port>
<username>userid</username>
<password>userpassword</password>
<nonProxyHosts>local.net|random.host.com</nonProxyHosts>
</proxy>
</proxies>
……
</settings>

It holds the HTTP proxy details required to connect to the network.
Id: It signifies the unique ID of the proxy.
Active: It is specified to set one proxy active from a list of proxies. The first proxy from the set will be active unless specified.
Protocol, host, port: As the name suggests, it declares the protocol, host, and port of the proxy.
Username, password: It denotes the authentication information required to access the proxy.
NonProxyHosts: It is a list of proxy hosts that should not be connected. The expected type of proxy serves as the delimiter.

Profiles

The profile element consists of activation, repositories, plugin repositories, and properties as they configure the build system.
The profiles allow you to group these configurations in various ways, which can modify the build process.
It is a truncated version of pom.xml profiles. An active profile from the settings can override profiles from pom.xml or profiles.xml in the case of equivalent IDs’.

Activation

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
…….
<profiles>
<profile>
<id>idname</id>
<activation>
<activeByDefault>false</activeByDefault>
<jdk>1.4</jdk>
<os>
<name>Windows 11</name>
<family>Windows</family>
<arch>i5</arch>
<version>11.0</version>
</os>
<property>
<name>mavenVersion</name>
<value>2.0.3</value>
</property>
<file>
<exists>${bdirec}/one.properties</exists>
<missing>${bdirec}/two.properties</missing>
</file>
</activation>
……
</profile>
</profiles>
…….
</settings>

Profiles can modify values under the circumstances specified in the activation element.
There are four criteria specified for activation. However, it is optional to meet all the requirements.
Jdk: It is a built-in test that activates when the JDK version specified matches the given prefix.
Os: It activates when the operating system properties mentioned are met.
Property: Activation occurs when Maven detects the specified property value.
File: It activates based on the existence of the given filename.

Properties of Maven Settings.XML

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
…..
<profiles>
<profile>
…….
<properties>
<user.project.folder>path.to.userproject </user.project.folder>
</properties>
……
</profile>
</profiles>
…..
</settings>

Maven properties are value placeholders accessible within the pom.xml when invoked using ${property_name}.
Five different styles are accessible anywhere from settings.xml.
X: The property with the envprefix will return the environment variable.
x: This property returns the corresponding values from the pom.xml’s project element.
x: Similarly, this property invokes the corresponding values from settings.xml.
Java System Properties: With java.lang.System.getProperties(), we may access all pom.xml properties.
x: If fixed within the properties element, the value can be accessible as ${someVar}.

Repositories

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
…..
<profiles>
<profile>
…..
<repositories>
<repository>
<id>maven-snapshots</id>
<name>Maven Snapshots</name>
<releases>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>warn</checksumPolicy
</snapshots>
<url> http://people.apache.org/repo/snapshotrepositoryurl </url>
<layout>default</layout>
</repository>
</repositories>
……
</profile>
</profiles>
……
</settings>

Maven’s local repository occupies repositories which is a remote collection of projects. This local repository is crucial in calling the Maven artifacts.
Each remote repository may contain different projects that can have matching release or snapshot artifacts in the active profile.
releases, snapshots: They denote the policies for artifact, release, or snapshot that empowers pom.xml to change.
enabled: Indicates whether this repository is enabled for the specific type.
updatePolicy: It determines the frequency of the updates.
checksumPolicy: Maven deploys files with related checksum files to the repository. You can choose to ignore, fail or warn about faulty checksums.
layout: Declare default or legacy using this element.

Plugin Repositories

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
…..
<profiles>
<profile>
.….
<pluginRepositories>
<pluginRepository>
<id>maven-plugin-repo</id>
<name>Maven Public Repositories</name>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
<url>http://people.apache.org/repo/pluginrepourl</url>
</pluginRepository>
</pluginRepositories>
……
</profile>
</profiles>
……
</settings>

Repositories are the home to dependencies and plugins, the primary Maven artifacts.
The plugin repositories element is similar to the repositories element. Since Maven plugins are distinctive, we separate the plugin repositories from other repositories.

Active Profiles

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
……
<activeProfiles>
<activeProfile>activeprofile1</activeProfile>
<activeProfile>activeprofile2</activeProfile>
</activeProfiles>
</settings>

The final element of the settings.xml activeProfile, allows you to specify profile IDs of default profiles active for all builds.
Active profiles mentioned will be active irrespective of environmental settings.

Conclusion

pom.xml is Maven’s one-stop for all the details regarding the project. But for best practices, we need external settings files to configure the Maven execution. The settings.xml contains nine possible child elements configuring environmental specifics like local and remote repository locations.

FAQs

Q1. Is settings.xml same as pom.xml?

Answer: pom.xml is the core of Maven’s functionality. It contains information on build configurations, dependencies, and other critical project details. Settings are maintained externally to make the pom.xml independent of the developer’s environment. Hence settings.xml has the system and/or user configurations that are not part of the pom.xml. Like the server credentials, which we don’t want in the source code.

Q2. Where is Maven settings.xml?

Answer: The two places where Maven settings.xml found are Global settings in ${maven.home}/conf/settings.xml, User settings in ${user.home}/.m2/settings.xml. You can also override the default locations of the settings from the command line. e.g.: To set user settings location to c:\user\settings.xml

$ mvn clean –global-settings c:\user\settings.xml

Q3. Which settings.xml is Maven using?

Answer: The settings files located in Maven are global settings and user settings. Maven uses either one or both of the settings.xml files. If both files are present, then the files are combined with user-specific settings taking precedence.

Quiz Result
Total Questions	Correct Answers	Wrong Answers	Percentage