Installing Maven

Introduction

This chapter contains very detailed instructions for installing Maven on a number of different platforms. Instead of assuming a level of familiarity with installing software and setting environment variables, we’ve opted to be as thorough as possible to minimize any problems that might arise due to a partial installation. The only thing this chapter assumes is that you’ve already installed a suitable Java Development Kit (JDK). If you are just interested in installation, you can move on to the rest of the book after reading through Section 2.2, “Downloading Maven” and Section 2.3, “Installing Maven”. If you are interested in the details of your Maven installation, this entire chapter will give you an overview of what you’ve installed and the meaning of the Apache Software License, Version 2.0.

2.1. Verify your Java Installation

The latest version of Maven currently requires the usage of Java 7 or higher. While older Maven versions can run on older Java versions, this book assumes that you are running at least Java 7. Go with the most recent stable Java Development Kit (JDK) available for your operating system.

Tip

More details about Java version required for different Maven versions can be found on theMaven site.

Maven works with all certified Java^TM compatible development kits, and a few non-certified implementations of Java. The examples in this book were written and tested against the official Java Development Kit releases downloaded from the Oracle web site.

2.2. Downloading Maven

You can download Maven from the Apache Maven project website at http://maven.apache.org/download.html.

When downloading Maven, you can download the latest available version the latest available version of Maven 3 in various branches. The latest version of Maven 3 when this book was last updated was Maven 3.3.3. If you are not familiar with the Apache Software License, you should familiarize yourself with the terms of the license before you start using the product. More information on the Apache Software License can be found in Section 2.8, “About the Apache Software License”.

Tip

We recommend to avoid Maven 2 as it is no longer maintained and use the latest version of Maven 3 available and listed as the current stable version.

To download Maven , go to and select the appropriate binary archive format for your platform. The contents of the zip or tar.gz are the same.

2.3. Installing Maven

• 2.3.1. Installing Maven on Linux, BSD or Mac OSX
• 2.3.2. Installing Maven on Microsoft Windows

There are wide differences between operating systems such as Mac OS X and Microsoft Windows, and there are subtle differences between different versions of Windows. Luckily, the process of installing Maven on all of these operating systems is relatively painless and straightforward. The following sections outline the recommended best-practice for installing Maven on a variety of operating systems.

2.3.1. Installing Maven on Linux, BSD or Mac OSX

You can download a binary release of Maven from http://maven.apache.org/download.html. Download the current release of Maven in a format that is convenient for you to work with. Pick an appropriate place for it to live, and expand the archive there. If you expanded the archive into the directory /opt/apache-maven-3.2.5, you may want to create a symbolic link to make it easier to work with and to avoid the need to change any environment configuration when you upgrade to a newer version:

Once Maven is installed, you need to do a couple of things to make it work correctly. You need to add its bin directory in the distribution (in this example, /opt/maven/bin) to your command path.

You’ll need to add PATH to a script that will run every time you login. To do this, add the following lines to .bash_login or .profile

Once you’ve added these lines to your own environment, you will be able to run Maven from the command line.

Note

These installation instructions assume that you are running bash.

2.3.2. Installing Maven on Microsoft Windows

Installing Maven on Windows is very similar to installing Maven on Mac OSX, the main differences being the installation location and the setting of an environment variable. This book assumes a Maven installation directory of c:\Program Files\apache-maven-3.2.5, but it won’t make a difference if you install Maven in another directory as long as you configure the proper environment variables. Once you’ve unpacked Maven to the installation directory, you will need to set the PATH environment variable. You can use the following commands:

Setting these environment variables on the command-line will allow you to run Maven in your current session, but unless you add them to the System environment variables through the control panel, you’ll have to execute these two lines every time you log into your system. You should modify both of these variables through the Control Panel in Microsoft Windows.

2.4. Testing a Maven Installation

Once Maven is installed, you can check the version by running mvn -v from the command-line. If Maven has been installed, you should see something resembling the following output.

If you see this output, you know that Maven is available and ready to be used. If you do not see this output, and your operating system cannot find the mvn command, make sure that your PATH environment variable and M2_HOME environment variable have been properly set.

2.5. Maven Installation Details

• 2.5.1. User-specific Configuration and Repository
• 2.5.2. Upgrading a Maven Installation

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.

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.txtcontains 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.

Note

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:

~/.m2/settings.xml

A file containing user-specific configuration for authentication, repositories, and other information to customize the behavior of Maven.

~/.m2/repository/

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.

Note

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 Linux, BSD or Mac OSX”, it should be easy to upgrade to newer versions of Maven when they become available. Simply install the newer version of Maven (/opt/maven-3.future) next to the existing version of Maven (/opt/maven-3.2.5). Then switch the symbolic link /opt/maven from /opt/maven-3.2.5 to /opt/maven-3.future. Since, you’ve already set your M2_HOME variable to point to /opt/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-3.future and update your M2_HOME variable.

Note

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.6. Uninstalling Maven

Most of the installation instructions involve unpacking of the Maven distribution archive in a directory and setting of various environment variables. If you need to remove Maven from your computer, all you need to do is delete your Maven installation directory and remove the environment variables. You will also want to delete the ~/.m2 directory as it contains your local repository.

2.7. Getting Help with Maven

While this book aims to be a comprehensive reference, there are going to be topics we will miss and special situations and tips which are not covered. While the core of Maven is very simple, the real work in Maven happens in the plugins, and there are too many plugins available to cover them all in one book. You are going to encounter problems and features which have not been covered in this book; in these cases, we suggest searching for answers at the following locations:

maven.apache.org

This will be the first place to look, the Maven web site contains a wealth of information and documentation. Every plugin has a few pages of documentation and there are a series of "quick start" documents which will be helpful in addition to the content of this book. While the Maven site contains a wealth of information, it can also be a frustrating, confusing, and overwhelming. There is a custom Google search box on the main Maven page that will search known Maven sites for information. This provides better results than a generic Google search.

Maven User Mailing List

The Maven User mailing list is the place for users to ask questions. Before you ask a question on the user mailing list, you will want to search for any previous discussion that might relate to your question. It is bad form to ask a question that has already been asked without first checking to see if an answer already exists in the archives. There are a number of useful mailing list archive browsers, we’ve found Nabble to the be the most useful.

www.sonatype.com

Sonatype maintains an online copy of this book and other tutorials related to Apache Maven.

2.8. About the Apache Software License

Apache Maven is released under the Apache Software License, Version 2.0. If you want to read this license, you can read ${M2_HOME}/LICENSE.txt or read this license on the Open Source Initiative’s web site here: http://www.opensource.org/licenses/apache2.0.php.

There’s a good chance that, if you are reading this book, you are not a lawyer. If you are wondering what the Apache License, Version 2.0 means, the Apache Software Foundation has assembled a very helpful Frequently Asked Questions (FAQ) page about the license available here: http://www.apache.org/foundation/licence-FAQ.html. Here’s is the answer to the question "I am not a lawyer. What does it all mean?"

[This license] allows you to:

• freely download and use Apache software, in whole or in part, for personal, company internal, or commercial purposes;
• use Apache software in packages or distributions that you create.

It forbids you to:

• redistribute any piece of Apache-originated software without proper attribution;
• use any marks owned by The Apache Software Foundation in any way that might state or imply that the Foundation endorses your distribution;
• use any marks owned by The Apache Software Foundation in any way that might state or imply that you created the Apache software in question.

It requires you to:

• include a copy of the license in any redistribution you may make that includes Apache software;
• provide clear attribution to The Apache Software Foundation for any distributions that include Apache software.

It does not require you to:

• include the source of the Apache software itself, or of any modifications you may have made to it, in any redistribution you may assemble that includes it;
• submit changes that you make to the software back to the Apache Software Foundation (though such feedback is encouraged).