Using Maven in IntelliJ IDEA

IntelliJ IDEA has first-class support for Maven built right in. This chapter shows you how to make IntelliJ use the Maven you installed earlier, how to import and navigate projects, and how to use the most common shortcuts that speed up daily development.

Prerequisites

• IntelliJ IDEA installed (Community or Ultimate edition)
• Maven installed as described in the previous chapter
• A basic understanding of the Maven lifecycle

Configuring the Bundled Maven

IntelliJ ships with its own copy of Maven, but you should point it to the one you installed on your system. This guarantees that builds inside the IDE and builds on the command line behave identically.

Open Settings (Windows/Linux: Ctrl + Alt + S, macOS: Cmd + ,) and navigate to Build, Execution, Deployment → Build Tools → Maven.

Look for the Maven home path field. It probably shows a path deep inside the IntelliJ application folder. Change it to your own installation:

Also check the User settings file and Local repository fields. They should point to:

• User settings file: ~/.m2/settings.xml
• Local repository: ~/.m2/repository

Click Apply or OK to save.

Importing a Maven Project

Opening an Existing Project

1. From the welcome screen, choose Open (or File → Open if a project is already loaded).
2. Navigate to the project folder and select the pom.xml file, or simply select the project root folder.
3. IntelliJ detects the Maven structure automatically and begins importing.

During import, IntelliJ downloads declared dependencies and builds an internal project model. You will see a progress bar at the bottom. Wait for it to finish before running code.

Recognizing a Maven Project in the IDE

Once imported, the Project tool window on the left shows the standard Maven directory structure. Files and folders are color-coded:

• Blue folders: source roots (src/main/java)
• Green folders: test roots (src/test/java)
• Orange folders: resource roots (src/main/resources)
• Red text: files with compilation errors

If the structure looks wrong — for example, src/main/java appears as a plain folder instead of a blue one — the Maven import probably failed. Right-click the pom.xml and choose Maven → Reload Project.

The Maven Tool Window

Open it from the right-hand tool window bar or via View → Tool Windows → Maven.

The Maven tool window is split into several useful areas:

Lifecycle

Lists the standard Maven phases: clean, validate, compile, test, package, verify, install, deploy. Double-click any phase to run it.

Plugins

Shows plugins declared in your pom.xml and their available goals. This is handy when you want to run a specific goal — such as dependency:tree — without typing it in the terminal.

Dependencies

Displays the full dependency tree of your project. Expand any node to see transitive dependencies. If two versions of the same library exist, IntelliJ highlights the conflict.

Essential Shortcuts and Actions

Reloading the Project

Any time you edit pom.xml — adding a dependency, changing a version, or tweaking a plugin — IntelliJ usually prompts you with a small Maven icon in the top-right corner of the editor. Click it to reload.

If the icon does not appear, use the shortcut above, or open the Maven tool window and click the Reload button (two circling arrows).

Running and Debugging

You can run your application in several ways:

1. Via the Maven tool window: Expand the Lifecycle list and double-click compile or package.
2. Via a run configuration: Right-click a class with a main method and choose Run or Debug.
3. Via the terminal: Open the built-in terminal (Alt + F12 / Option + F12) and type Maven commands exactly as you would in a standalone shell.

Viewing the Dependency Tree

When dependency conflicts arise, the visual tree is the fastest way to understand what is happening.

Open the Maven tool window, go to the Dependencies tab, and type a library name into the filter box at the top. IntelliJ narrows the tree to matching entries and shows the version that won and the versions that were excluded.

If you prefer the command line, open the built-in terminal and run:

# Print the dependency tree
mvn dependency:tree

For a specific library:

# Filter the tree for a single artifact
mvn dependency:tree -Dincludes=com.fasterxml.jackson.core

FAQ

IntelliJ does not recognize src/main/java as a source folder. What should I do?

Right-click the pom.xml in the project root and choose Maven → Reload Project. If that fails, close the project, delete the .idea folder and any *.iml files, then reopen the project by selecting pom.xml.

How do I force IntelliJ to re-download all dependencies?

In the Maven tool window, click the Reload button while holding Ctrl (or Cmd on macOS). Alternatively, run mvn dependency:purge-local-repository in the terminal to wipe and re-fetch everything.

Can I use IntelliJ with Maven and Gradle in the same workspace?

Each project has one primary build tool. IntelliJ detects whether the root contains a pom.xml or a build.gradle and configures itself accordingly. You can open separate windows for Maven and Gradle projects.

Why do terminal builds fail while IDE builds succeed?

Usually a mismatch between the Maven versions or the JAVA_HOME settings. Double-check that IntelliJ's Maven home path points to your standalone installation and that the terminal inherits the same environment variables.

Where can I see the effective POM that IntelliJ is using?

In the Maven tool window, right-click your project node and choose Show Effective POM. This opens a read-only XML file that merges the project POM with all parent POMs and active profiles — useful for debugging inherited settings.