Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 41 ยท Getting Started

Maven in IntelliJ IDEA, Eclipse and VS Code

Create a Maven project in IntelliJ IDEA or Eclipse, import an existing one, reload after POM changes, run goals from the IDE and fix the usual JDK and sync problems.

You can do everything in Maven from a terminal, and you should know how. But most Java developers spend the day in an IDE (integrated development environment) such as IntelliJ IDEA, Eclipse or Visual Studio Code. The good news is that all three understand pom.xml natively: they read your dependencies for code completion, compile with the same settings as Maven, and let you run lifecycle phases with a click.

The trick is to treat the POM as the single source of truth and the IDE as a view of it. This lesson shows how to create and import projects in the main IDEs, how to reload after changes, how to run goals, and how to fix the handful of problems that cause most confusion. The IDEs cannot run on this site, so the menus are described in words and the runnable example is a stand-in that checks whether your IDE and POM agree. Menu names vary between versions, so look for the equivalent in yours.

The golden rule

Everything that matters for the build goes into the pom.xml: dependencies, Java version, plugins, encoding. The IDE reads it and configures itself. If you instead change dependencies inside the IDE's own project settings (adding a JAR by hand, for example), the IDE builds fine on your machine and Maven fails on the build server. Whatever the IDE shows should be reproducible with mvn verify on a clean checkout.

IntelliJ IDEA

Create a new project. Choose New Project, then pick Maven as the build system (in recent versions, "Java" with the build system set to Maven). Enter the name and location, choose the JDK, and expand Advanced Settings to set the GroupId and ArtifactId. IntelliJ writes a pom.xml and the standard folders (see The Standard Directory Layout). Choosing an archetype is optional; most people skip it.

Open an existing Maven project. Use File, Open and select the folder that contains pom.xml (or the pom.xml file itself). IntelliJ imports it as a Maven project, downloads the dependencies and indexes them. For a multi-module build, open the parent folder and all modules appear (see Multi-Module Builds and the Reactor).

Reload after a change. After editing pom.xml, a small Load Maven Changes button (an "m" icon) appears. Click it, or use the Maven tool window (right side) and press Reload All Maven Projects. You can enable auto-reload in the settings, but many people prefer the explicit click because a half-edited POM triggers a failing import.

Run goals. The Maven tool window lists Lifecycle (clean, compile, test, package, verify, install, deploy) and Plugins. Double-click a phase to run it. For custom commands, use Run, Edit Configurations, Maven and type the goals, such as clean verify -DskipITs.

Where the settings live. Settings, Build, Execution, Deployment, Build Tools, Maven controls the Maven installation (bundled, or your own, or the wrapper mvnw; see Installing Maven and the Wrapper), the settings.xml file and the local repository path. Select Use Maven wrapper if the project has one, so everyone uses the same Maven version.

Eclipse

Eclipse for Java developers includes m2e, its Maven integration.

  • Create: File, New, Maven Project. Choose Create a simple project to skip archetypes, or select an archetype such as maven-archetype-quickstart. Enter the group id, artifact id and version; choose the packaging (jar or war).
  • Import: File, Import, Maven, Existing Maven Projects, then select the root directory. Eclipse lists the modules it finds.
  • Refresh: after changing the POM, right-click the project, then Maven, Update Project (shortcut Alt+F5). Tick Force Update of Snapshots/Releases when a dependency was published late.
  • Run: right-click the project, Run As, Maven build... and type the goals (clean install), or choose a predefined Maven install, Maven test.
  • Console: open the Maven Repositories view to browse the local cache and rebuild indexes.

m2e takes the Java level from maven-compiler-plugin settings (maven.compiler.release or source/target) and applies it to the project. If Eclipse shows an old Java level, run Update Project.

Visual Studio Code

Install the Extension Pack for Java (it includes Maven for Java) and a JDK. VS Code recognizes folders with a pom.xml. The Maven view lists projects, lifecycle phases and dependencies; use the Java Projects view to see packages and referenced libraries. New project: command palette, Java: Create Java Project, then choose Maven. Run phases from the Maven view, or from the integrated terminal with ./mvnw verify, which is often the most predictable way in VS Code.

Always set the Java version in the POM

Most "it works in Maven but not in the IDE" (and the reverse) problems come from two different Java versions: the JDK that runs Maven, the JDK the IDE uses to compile, and the language level the POM requests. Declare the level once in the POM:

XML
<properties>
  <maven.compiler.release>21</maven.compiler.release>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

The IDE imports that setting as the project's language level. Then make sure the IDE's project SDK is a JDK of at least that version. If you open a project that needs Java 21 and the IDE uses JDK 17, you get errors such as invalid target release or release version 21 not supported, which are fixed by selecting the right JDK in the project structure and Maven importer settings, not by editing source code. See Properties and Build Settings.

Typical problems and fixes

Symptom Likely cause Fix
Red imports after editing the POM Project not reloaded Reload (IntelliJ), Update Project (Eclipse)
"Cannot resolve" for a dependency that Maven downloads fine IDE uses a different settings.xml or local repository Point the IDE at the same settings.xml, see settings.xml, Mirrors and Credentials
Dependency stuck as "unresolved" after a failed download Cached failure (.lastUpdated files) Run mvn -U once or delete the .lastUpdated files, then reload
Different Maven version than the terminal IDE bundled Maven Select the wrapper or your installation
Tests run in the terminal but not in the IDE Old JUnit or missing engine Check the test dependencies and Surefire (see Running Tests with Surefire)
Wrong Java level JDK mismatch Set maven.compiler.release, then fix the IDE JDK
Generated sources not found Folder not marked as source root Reload; check the plugin's output directory is registered
Module not seen in a multi-module project Opened a child instead of the parent Open the parent POM folder

When the IDE and the terminal disagree, trust the terminal: ./mvnw clean verify is what the build server will run, and the answer from there decides whether the build is healthy.

A stand-in consistency check

The program below plays the role of "is my IDE aligned with my POM?". It takes the Java level and Maven version the POM or wrapper asks for, compares them with what the IDE uses, and prints the fixes. It is a model of the reasoning, not of any IDE's code.

Java Does the IDE agree with the POM?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Laptop C shows that a newer IDE JDK than the release level is fine, because --release 17 makes the compiler behave as Java 17, while an older JDK (laptop B) cannot compile Java 21 code at all.

Habits that keep IDE and Maven in sync

  • Create projects from a POM-first workflow, and commit pom.xml, mvnw and .mvn/ but not IDE folders (.idea/, .settings/, .classpath, .project). Add them to .gitignore.
  • Use the wrapper in both IDE and terminal.
  • Reload, then build once with mvn verify after big dependency changes.
  • Do not add JARs manually in IDE settings; add a dependency to the POM instead. Local files that are not in any repository are the rare case; see Adding Dependencies for ways to handle it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You add a dependency to pom.xml and the IDE still shows red imports. What should you do first?

    The IDE reads the POM when it imports; a reload applies your change.
  2. 2. The POM sets maven.compiler.release to 21 and the IDE uses JDK 17. What happens?

    A JDK cannot compile for a release newer than itself, so choose a JDK of at least the requested version.
  3. 3. The IDE and the terminal give different results. Which result should you trust?

    The CI server runs Maven, not your IDE, so the command-line result decides.
  4. 4. Which files should normally not be committed?

    IDE project folders are personal and generated from the POM.

Summary

  • The POM is the source of truth; IDEs (IntelliJ IDEA, Eclipse with m2e, VS Code with the Java extensions) import it and run Maven goals.
  • Create projects with New Project, Maven (or New Maven Project), or open the folder with pom.xml; for multi-module builds open the parent.
  • Reload or Update Project after POM edits, and run phases from the Maven tool window or terminal.
  • Set maven.compiler.release in the POM and make the IDE's JDK at least that version; use the wrapper and the same settings.xml.
  • When IDE and terminal disagree, trust ./mvnw clean verify.

Next: Your First Maven Project.