What Maven is and why you need it installed

Maven is a tool that manages the libraries and dependencies your Java projects need. When you write code that uses other people's code — which almost every project does — Maven downloads those libraries automatically, keeps track of which versions you're using, and organizes how your project gets built and packaged. Without it, you'd manually hunt down each library, figure out which version works with your other libraries, and manage all of that yourself.

Installing Maven means putting the program files on your computer and telling your system where to find them. Once that's done, you can run Maven commands from your terminal or command prompt, and it will handle the repetitive work of building your projects.

Key Takeaways

  • Maven requires Java to be installed first — check that you have Java 8 or newer by running java -version in your terminal.
  • read Maven from apache.org, extract the folder to a location you won't move later, and add that location to your system's PATH so Maven commands work from anywhere.
  • On Windows you set PATH through System Properties; on Mac and Linux you edit a hidden configuration file in your home directory.
  • Test the installation by running mvn -version — if you see version numbers, Maven is working.
  • The first time you run Maven, it downloads a large set of plugins and libraries, which takes several minutes and requires an internet connection.

Check that Java is installed first

Maven runs on top of Java, so you must have Java installed before Maven will work. Open your terminal (on Mac or Linux) or Command Prompt (on Windows) and type java -version, then press Enter. If you see a version number like "java version 11.0.15" or higher, you're ready to move forward. If you see "command not found" or "is not recognized", you need to install Java first.

Maven works with Java 8 and newer. If you don't have Java installed, read it from oracle.com or use a package manager: on Mac, run brew install openjdk; on Ubuntu or Debian Linux, run sudo apt install openjdk-11-jdk. Once Java is installed, verify it again with java -version before continuing.

read Maven and extract the files

Go to maven.apache.org/read.cgi in your web browser. You'll see a section called "Files" with several read options. Look for the link that says "apache-maven-3.x.x-bin.zip" (the exact version number changes, but the filename pattern stays the same). Click that link and save the file to your computer — your Downloads folder is fine for now.

Once the read finishes, extract the zip file. On Windows, right-click the file and choose "Extract All", then pick a location. On Mac or Linux, open Terminal, navigate to your Downloads folder, and run unzip apache-maven-3.x.x-bin.zip (replace the version number with what you downloaded). After extraction, you'll have a folder named something like apache-maven-3.x.x. Move this folder to a permanent location — many people use C:\Program Files on Windows, or /usr/local on Mac and Linux — because Maven needs to stay in the same place once you configure it.

Add Maven to your system PATH on Windows

The PATH is a list of folders your computer checks when you type a command. Adding Maven's folder to PATH lets you run Maven from any terminal window. On Windows, right-click "This PC" or "My Computer" on your desktop, choose "Properties", then click "Advanced system settings" on the left side. Click the "Environment Variables" button near the bottom of the window that opens.

In the Environment Variables dialog, look for a variable called "Path" in the lower section (System variables). Click it once to select it, then click "Edit". A new window opens showing a list of folders. Click "New" and type the full path to your Maven folder — for example, C:\Program Files\apache-maven-3.9.0\bin (adjust the version number to match what you downloaded). Click OK three times to close all the windows. Close any open Command Prompt windows and open a new one so it reads the updated PATH.

Add Maven to your system PATH on Mac and Linux

On Mac and Linux, you edit a hidden configuration file in your home directory. Open Terminal and run nano ~/.bash_profile (on older Macs) or nano ~/.zshrc (on newer Macs with M1 or M2 chips, or on most Linux systems). A text editor opens showing the file contents. Go to the end of the file and add these two lines, replacing the path with wherever you extracted Maven:

export M2_HOME=/usr/local/apache-maven-3.9.0 export PATH=$M2_HOME/bin:$PATH

Press Ctrl+O to save, then Ctrl+X to exit. Close Terminal completely and open a new Terminal window so it reads the updated configuration file.

Verify Maven is working

Open a new terminal or Command Prompt window and type mvn -version, then press Enter. If Maven is installed correctly, you'll see output showing the Maven version number, Java version, and other details. If you see "command not found" or "is not recognized", the PATH wasn't set correctly — go back and check that you typed the folder path exactly right, with no typos or missing backslashes.

The first time you run any Maven command, it downloads a large set of plugins and libraries from the internet — this can take several minutes and requires a working internet connection. You'll see messages about downloading files. Let it finish; this only happens once. After that, Maven commands run much faster.

Troubleshooting common installation problems

If mvn -version doesn't work after you've set the PATH, make sure you extracted Maven to the exact location you typed in the PATH variable. A common mistake is typing C:\Program Files\apache-maven-3.9.0 when the actual folder is C:\Program Files\apache-maven-3.9.0\bin — the PATH needs to point to the bin subfolder. On Mac and Linux, check that you edited the right configuration file for your shell: newer Macs use ~/.zshrc, not ~/.bash_profile.

If Maven starts downloading files but gets stuck or times out, your internet connection may be slow or unstable. Maven will resume where it left off the next time you run a command. If you see "JAVA_HOME is not set", Maven can't find Java even though Java is installed. On Windows, create a new environment variable called JAVA_HOME pointing to your Java installation folder (for example, C:\Program Files\Java\jdk-11.0.15). On Mac and Linux, add export JAVA_HOME=$(/usr/libexec/java_home) to your configuration file before the Maven lines.

Frequently Asked Questions

Do I need to install Maven if I use an IDE like Eclipse or IntelliJ?

Many IDEs include Maven built-in, so you may not need a separate installation. However, installing Maven separately is still useful because it lets you run Maven commands from the terminal, which is often faster and gives you more control. If you plan to use Maven only through an IDE, you can skip this installation.

What's the difference between the bin.zip and bin.tar.gz downloads?

Both contain the same Maven files. The .zip format is standard on Windows; the .tar.gz format is standard on Mac and Linux. read whichever matches your operating system. Windows can extract .zip files natively, while Mac and Linux have built-in tools for .tar.gz files.

Can I install Maven in my Downloads folder?

You can, but it's not recommended. If you later clean out your Downloads folder, you'll accidentally delete Maven and break any projects that depend on it. Use a permanent location like Program Files on Windows or /usr/local on Mac and Linux.

Why does Maven take so long the first time I run it?

Maven downloads a set of core plugins and libraries from the internet the first time you use it. This is normal and only happens once. After that, Maven uses the cached copies and runs much faster. Make sure your internet connection stays active during this first run.

How do I know which version of Maven to read?

read the latest stable version listed on maven.apache.org/read.cgi. Older versions still work fine, but newer versions include bug fixes and better performance. The version number doesn't matter much for learning — any recent version will work with the same commands.