The installation of Maven can trip some people up. The installation instructions are actually at the bottom of the download page which is not where I would look for them to be honest, I’d go straight for the documentation pages, which don’t seem to have this information. The instructions also assume a fair degree of familiarity with your OS and might be a little vague for a relative beginner.

Your operating system may include Maven by default, or provide installation packages. These are likely to work fine and will generally take care of all the steps mentioned here. Install them if you want. I personally like to try to keep Java applications separated from OS concerns, it just seems right to me to do it that way. Your milage may vary. You also might want to install another copy of a different version to that supplied by your OS vendor and keep the two separate.

Here’s how to install Maven in your local user account on any unix OS (Linux, MacOS X, Solaris etc). This does not require root privileges. Doing this on a MS Windows operating system is basically the same, you just define the variables in a different place. I may followup with those details at a later date.

  1. Java must be installed.

    Maven is a pure Java application and requires at least Java 1.5. See http://shinysparkly.wordpress.com/2009/10/28/local-java/ for help installing Java.

  2. Download Maven.

    Go to http://maven.apache.org, click on Download under Get Maven on the left-hand side of the page towards the top. There are a few different versions listed on the downloads page, the most recent at the top. At time of writing the most recent was 2.2.1. There are compiled and source distributions in several flavours of archive format. For general ease of use I recommend the compiled version in zip format, i.e. apache-maven-2.2.1-bin.zip. Click on the link and it takes you to an apache.org mirror server selection page, pick the first one and the file will start downloading. If there is an error and try one of the other mirrors.

    Download and save the zip file to your home directory.

  3. Installing Maven

    Unzip the zip file. It will create a apache-maven-2.2.1 directory. You can move this directory somewhere else if you wish. On MacOS X I recommend moving it into your ~/Library directory. You can also rename this directory, although I recommend not to, it’s not a bad name as directories go. The following instructions assume that you do not renamed this directory and leave it in your home directory.

  4. Setup your Environment

    This step is generally where people get unglued. You need to add two environment variables and append the bin directory from your new Maven install. You can do this by editing your ~/.bash_profile.

    You need to add a variable called M2_HOME and give it the value of the directory path to your new Maven installation:

    export M2_HOME=/home/username/apache-maven-2.2.1

    Then add a M2 variable and point it to the bin directory of the install:

    export M2=$M2_HOME/bin

    Note how we reuse the M2_HOME variable here. This is handy in case you have to move or otherwise change the Maven directory you only have to update it here once, and not twice.

    Then you need to add the M2 directory to the start of your path. Something like:

    export PATH=$M2:$PATH

    By including M2 at the beginning of your path it ensures that this version of Maven will be the one that is found, even if there other versions installed on your operating system. This is handy if your operating system already has a version of Maven installed that you don’t want to use but can’t remove or don’t want to remove (MacOS X I am looking at you).

    You can force the changes to take effect within a single terminal session with the following command but it is recommended to logout and back in again.

    [localhost]$ source ~/.bash_profile

And that’s it.

  1. Verify the Changes

    To verify that the changes have been correctly done, open a terminal and run the following commands:

    To display the directory where you installed Maven

    [localhost]$ echo $M2_HOME

    /home/username/apache-maven-2.2.1

    To display should should the bin directory of your Maven install.

    [localhost]$ echo $M2

    /home/username/apache-maven-2.2.1/bin

    To display the comma separated list of directories where the shell will search for commands. It should have the bin directory of your Maven install at the beginning.

    [localhost]$ echo $PATH

    /home/username/apache-maven-2.2.1/bin:/home/username/jdk1.6.0_16/bin:/usr/lib/qt-3.3/bin:/usr/kerberos/bin:/usr/local/bin:/bin:/usr/bin

    To display the complete path to the Maven executable, mvn, which should be in the bin directory of your Maven install.

    [localhost]$ which mvn

    /home/username/apache-maven-2.2.1/bin/mvn

    To display the version from Maven, and related Java and operating system information.

    [localhost]$ mvn –version

    Maven version: 2.2.1

    Java version: 1.6.0_16

    OS name: “mac os x” version: “10.6.1” arch: “x86_64” Family: “mac”

And that’s it. There are no plugins or repositories to configure. That’s the beauty of Maven. All of that stuff can and should be configured in the POM (pom.xml) file for the project that requires it, and Maven takes care of retrieving and installing the plugins that it needs when it needs them.

There are a few cases where you would want to add some local configuration. This would generally go in your ~/.m2_conf/settings.xml. This is useful for configuration items that are specific to you or that you need to secure and not distribute. An example of this might be username and password configuration for a plugin used to access secured resources, such as uploading builds to a server.