Maven: The Complete Reference

2.5. Maven Installation Details

Maven’s download measures in at roughly 1.5 MiB, it has attained such a slim download size because the core of Maven has been designed to retrieve plugins and dependencies from a remote repository on-demand. When you start using Maven, it will start to download plugins to a local repository described in Section 2.5.1, “User-specific Configuration and Repository”. In case you are curious, let’s take a quick look at what is in Maven’s installation directory.

/usr/local/maven $ ls -p1

LICENSE.txt contains the software license for Apache Maven. This license is described in some detail later in the section Section 2.8, “About the Apache Software License”. NOTICE.txt contains some notices and attributions required by libraries that Maven depends on. README.txt contains some installation instructions. bin/ contains the mvn script that executes Maven. boot/ contains a JAR file (classwords-1.1.jar) that is responsible for creating the Class Loader in which Maven executes. conf/ contains a global settings.xml that can be used to customize the behavior of your Maven installation. If you need to customize Maven, it is customary to override any settings in a settings.xml file stored in ~/.m2. lib/ contains a single JAR file (maven-core-3.0.3-uber.jar) that contains the core of Maven.


Unless you are working in a shared Unix environment, you should avoid customizing the settings.xml in M2_HOME/conf. Altering the global settings.xml file in the Maven installation itself is usually unnecessary and it tends to complicate the upgrade procedure for Maven as you’ll have to remember to copy the customized settings.xml from the old Maven installation to the new installation. If you need to customize settings.xml, you should be editing your own settings.xml in ~/.m2/settings.xml.

2.5.1. User-specific Configuration and Repository

Once you start using Maven extensively, you’ll notice that Maven has created some local user-specific configuration files and a local repository in your home directory. In ~/.m2 there will be:

A file containing user-specific configuration for authentication, repositories, and other information to customize the behavior of Maven.
This directory contains your local Maven repository. When you download a dependency from a remote Maven repository, Maven stores a copy of the dependency in your local repository.


In Unix (and OSX), your home directory will be referred to using a tilde (i.e. ~/bin refers to /home/tobrien/bin). In Windows, we will also be using ~ to refer to your home directory. In Windows XP, your home directory is C:\Documents and Settings\tobrien, and in Windows Vista, your home directory is C:\Users\tobrien. From this point forward, you should translate paths such as ~/m2 to your operating system’s equivalent.

2.5.2. Upgrading a Maven Installation

If you’ve installed Maven on a Mac OSX or Unix machine according to the details in Section 2.3.1, “Installing Maven on Mac OSX” and Section 2.3.3, “Installing Maven on Linux”, it should be easy to upgrade to newer versions of Maven when they become available. Simply install the newer version of Maven (/usr/local/maven-2.future) next to the existing version of Maven (/usr/local/maven-3.0.3). Then switch the symbolic link /usr/local/maven from /usr/local/maven-3.0.3 to /usr/local/maven-2.future. Since, you’ve already set your M2_HOME variable to point to /usr/local/maven, you won’t need to change any environment variables.

If you have installed Maven on a Windows machine, simply unpack Maven to c:\Program Files\maven-2.future and update your M2_HOME variable.


If you have any customizations to the global settings.xml in M2_HOME/conf, you will need to copy this settings.xml to the conf directory of the new Maven installation.

2.5.3. Upgrading from Maven 1.x to Maven 2.x

If you are upgrading from Maven 1 to Maven 2, you are going to be using an entirely new POM and repository structure. If you have already created a custom Maven 1 repository to hold custom artifacts, you can use the Nexus Repository Manager to expose a Maven 1 repository in a format that can be understood by Maven 2 clients. For more information about the Nexus Repository Manager, see Repository Management with Nexus. In addition to tools like Nexus, you can also configure references to repositories to use the legacy layout format. For more information about configuring a reference to a legacy repository, see Section 15.2.8, “Repositories”.

If you have a set of Maven 1 projects, you may want to know about the Maven One Plugin. The Maven One Plugin was designed to help projects migrate from Maven 1 to Maven 2. If you have a Maven 1 project, you can convert the project’s POM by running the one:convert goal as follows:

$ cd my-project
$ mvn one:convert

one:convert will read a project.xml and produce a pom.xml that is compatible with Maven 2. If you’ve customized a Maven 1 build using Jelly script in a maven.xml file, you will need to investigate other options. While Maven 1 emphasized Jelly scripting for customizing builds, Maven 2 favors custom plugins or customization through scripting Plugins or the Maven Antrun Plugin.

The most important thing to know about when upgrading from Maven 1 to Maven 2 is that Maven 2 is a completely different build framework. Maven 2 introduces the concept of the Maven Lifecycle and redefines the relationships between plugins. If you upgrade from Maven 1 to Maven 2, you need to invest some time in learning about the differences between the two versions. Although it might seem straightforward to start learning about the new POM structure, you should focus on the Lifecycle first. If you understand the Maven Lifecycle, you will be able to use Maven to its fullest potential.