Best tutorial for Maven settings file | Sample mvn settings.xml example

Maven is a build tool designed for Java projects. Nowadays, most developers prefer Maven over Ant because Maven effectively handles their project dependencies.

What is the maven settings.xml file?

The settings.xml file configures Maven execution in various ways. It includes the following settings:

  • Local and remote repositories with security features enabled
  • Proxy configuration and server credentials.
  • maven profiles and active profiles

These settings are specific to the user where Maven is configured.

What are user and global settings XML file Location

There are two types of settings.xml files based on their location:

  • Global settings.xml
  • User settings.xml

Each Maven project utilizes either the user or global settings file. The default location for the global settings file is ${M2_HOME}/conf/settings.xml, where M2_HOME refers to the Maven installation directory.

The user settings file is located on your machine at~/.m2/settings.xml. Here, ~ symbolizes the user’s home directory.

What is a repository in Maven

In a Java application, various dependencies, such as Apache libraries, are crucial components for your project. To include these dependencies in your project, you need to specify them in the pom.xml file.

These libraries are accessible in Apache repositories. When you integrate Maven into your project, you must download these files. Once the dependencies are configured for your project, the associated libraries (JAR files) are initially downloaded to your local repository, usually hosted on your company’s server.

This local repository serves as a storage space for Java libraries obtained from various library repositories.

A repository is a location where dependencies, along with their specific versions, are stored. It serves as a source from which Maven can download these dependencies during the execution of a Maven project. This ensures that the required libraries and their designated versions are retrieved and incorporated seamlessly into the project.

What is a mirror in settings.xml of maven?

A mirror is a configuration in the settings.xml file used to set up mirrors for repository URLs.

These mirrors are set up to redirect requests to a specific repository. This enables requests to access repositories through a mirror server rather than directly reaching the repositories.

Mirrors help optimize network connections and improve download speeds.

<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>Asia</id>
    <name>Asia Central</name>
    <url>http://asia.maven.org/maven2</url>
    <mirrorOf>central</mirrorOf>
  </mirror>
</mirrors>
  • id and name serve as user-friendly, unique identifiers for a mirror.
  • url: This is the base URL for the mirror. When downloading repositories, Maven will connect to this mirror URL instead of the repository URL.
  • mirror: is a value, and when set to central, it refers to the Maven Central Repository. Other possible values include * and external.
  • mirrorOf: Specifies which URLs are mirrored. In this example, it is set to central.

In the provided instance, if any dependencies are attempting to download from the central repository, they will reach the mirror URL instead of the Maven Central Repository.

This capability allows us to prevent maven from attempting direct access from maven central Repository. directly.

Settings.xml sample example file

The settings.xml file encompasses the following elements:

  • profiles: Used for configuring environment-specific profiles such as dev, test, and stage.
  • servers: Contains details for configuring application server settings.
  • repositories: Specifies remote repository locations, such as the Maven Central Repository.
  • plugin repositories: Identifies the remote location for plugin repositories.
  • activeProfile: Indicates the active profile to be configured.
  • proxies: Configuration section for HTTP and HTTPS proxies.

Below is an example template for the settings.xml file:



<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
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <!-- profiles settings -->
  <profiles>
    <profile>
      <repositories>
        <repository></repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository></pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <!-- Server settings -->
  <server>
    <id>Websphere</id>
    <username>username</username>
    <password>password</password>
  </server>
  <!-- Proxy settings -->
  <proxies>
    <proxy>
      <id>userspecificproxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.com</host>
      <port>8080</port>
      <username>usernameofproxy</username>
      <password>passwordofproxy</password>
      <nonProxyHosts>configure here</nonProxyHosts>
    </proxy>
  </proxies>
  <!-- Repository settings -->
  <repositories></repositories>
  <!-- plugin repository settings -->
  <pluginRepositories></pluginRepositories>
  <!-- active profile -->
  <activeProfiles>
    <activeProfile>env-dev</activeProfile>
  </activeProfiles>
</settings>

How to find which settings.xml file is used?

We can set up the settings.xml in both global and local locations.

To figure out which settings.xml apply is using, there isn’t a specific maven command for users.

However, you can identify the location by enabling debugging logs when running the mvn command.

You can identify the location by enabling debugging logs while running the mvn command.

mvn clean -X

And output:

[DEBUG] Reading global settings from A:\Java\apache-maven-3.3.9\bin\..\conf\settings.xml
[DEBUG] Reading user settings from C:\Users\Kiran\.m2\settings.xml
[DEBUG] Reading global toolchains from A:\Java\apache-maven-3.3.9\bin\..\conf\toolchains.xml
[DEBUG] Reading user toolchains from C:\Users\Kiran\.m2\toolchains.xml
[DEBUG] Using local repository at C:\Users\Kiran\.m2\repository
[DEBUG] Using manager EnhancedLocalRepositoryManager with priority 10.0 for C:\Users\Kiran\.m2\repository

Enabling debugging logs during the mvn command will provide details about the locations of both the global settings and user settings files.

How to read the maven settings file in Java projects?

Maven offers the help:effective-settings command to read the settings file in Java projects. This command provides a consolidated view of the global and user settings.xml files along with other project-specific details.

It offers a consolidated overview of the effective settings configuration for the Maven build.

mvn help:effective-settings

This command solves some of the problems.

  • how to get Maven local repository location
  • how to find the Maven central repository location
Effective user-specific configuration settings:

<?xml version="1.0" encoding="Cp1252"?>
<!-- ====================================================================== -->
<!--                                                                        -->
<!-- Generated by Maven Help Plugin on 2021-06-15T15:12:25+05:30            -->
<!-- See: http://maven.apache.org/plugins/maven-help-plugin/                -->
<!--                                                                        -->
<!-- ====================================================================== -->
<!-- ====================================================================== -->
<!--                                                                        -->
<!-- Effective Settings for 'Kiran' on 'Kiran'                              -->
<!--                                                                        -->
<!-- ====================================================================== -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
  <localRepository>C:\Users\Kiran\.m2\repository</localRepository>
  <pluginGroups>
    <pluginGroup>org.apache.maven.plugins</pluginGroup>
    <pluginGroup>org.codehaus.mojo</pluginGroup>
  </pluginGroups>
</settings>


[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 35.076 s
[INFO] Finished at: 2021-06-15T15:12:25+05:30
[INFO] Final Memory: 17M/207M
[INFO] ------------------------------------------------------------------------

How to configure Proxy settings in settings.xml maven application

The settings.xml file includes a <proxies> tag to configure multiple proxy settings.

Below is an example of a settings.xml file illustrating the configuration of both HTTP and HTTPS proxies.

Each proxy configuration specifies the protocol, username, password, and host details:

<proxies>
  <!-- Http Proxy setting configuration-->
  <proxy>
    <id>optional</id>
    <active>true</active>
    <protocol>http</protocol>
    <username>proxyuser</username>
    <password>proxypass</password>
    <host>proxy-hostname.com</host>
    <port>80</port>
    <nonProxyHosts>otherhosts.com</nonProxyHosts>
  </proxy>
  <!-- HTTPS Proxy configuration details -->
  <proxy>
    <id>optional</id>
    <active>true</active>
    <protocol>https</protocol>
    <username>username</username>
    <password>password</password>
    <host>proxy-hostname.com</host>
    <port>80</port>
    <nonProxyHosts>otherhosts.com</nonProxyHosts>
  </proxy>
</proxies>

<id>: A unique identifier for each proxy configuration. <protocol>: Specifies the protocol (http or https). <host>: The host of the proxy server. <port>: The port number of the proxy server. <username> and <password>: Optional fields for proxy authentication. <nonProxyHosts>: Specifies a list of hosts that should bypass the proxy.

How to tell maven to take specific settings.xml file

Maven automatically considers both the user and global settings files by default.

If needed, you can override the user settings file using the mvn command with the -s option.

mvn -s c:/settings.xml

The global settings can be overridden using the -gs option in the mvn command.

mvn -gs c://users/adming/settings.xml

This functionality is applicable in Maven version 3.6.3 and later versions.