Working with Maven Projects in IntelliJ

Updated June 21, 2023

IntelliJ IDEA is a powerful Integrated Development Environment (IDE) widely used for Java project development. Maven is a software project management tool primarily used for managing Java projects. In this tutorial, we will be learning how to create new Maven projects in IntelliJ IDEA, handle dependencies, and work with the Maven tool.

1. Setting up IntelliJ IDEA and JDK

Before we get started with creating a Maven project, let's ensure we have the right setup. Download and install IntelliJ IDEA from the official website if you haven't already. Also, verify that you have Java Development Kit (JDK) installed on your machine.

1.1 Installing JDK

To confirm your JDK version, open the terminal and type java -version. If you see an output with a specific version, that means you have JDK installed. If not, refer to the official Java documentation to download and install the latest JDK.

1.2 Configuring JDK in IntelliJ IDEA

To add or configure JDK in IntelliJ IDEA:

  1. Open IntelliJ IDEA and go to File > Project Structure.
  2. In the dialog that opens, under Platform Settings, click on SDKs.
  3. Click the + button and navigate to the location of your installed JDK.
  4. Select the JDK folder and click OK.
  5. Click Apply and then OK.

2. Creating a New Maven Project

Now, let's dive into creating our first Maven project.

2.1 Starting a New Project

  1. In IntelliJ IDEA, go to New Project.

    Intellij Maven Guide (How It Works With Java PDF Library): Figure 1 - IntelliJ IDEA

  2. In the dialog that opens, select Maven on the build system.

    Intellij Maven Guide (How It Works With Java PDF Library): Figure 2 - New Project

  3. Check the Create from archetype box, which will allow you to select a Maven archetype—a template for your new project. For this example, choose maven-archetype-quickstart.
  4. Click Next.

2.2 Setting Project Metadata

In the next window:

  1. Specify GroupId, ArtifactId, and Version for your project. These properties identify your project in the local Maven repository.
  2. Choose a location to store your project files.
  3. Click Next, review your Maven settings, then click Finish.

Your new Maven project is now created! You'll see the project structure on the left in the tool window.

2.3 Understanding pom.xml

Each Maven project has a pom.xml file, short for Project Object Model, located at the root of your project directory. This file describes your project, its dependencies, and other properties.

Intellij Maven Guide (How It Works With Java PDF Library): Figure 3 - pom.xml file

The file might look complicated at first glance, but it's straightforward. Let's break it down:

  1. <modelVersion>: This is the version of the project model this POM is using.
  2. <groupId>: The ID of the project's group.
  3. <artifactId>: The ID of the artifact (project).
  4. <version>: The version of the artifact (project).
  5. <dependencies>: This section is where you specify all the dependencies your project needs.

3. Working with Dependencies in Maven

Dependencies are external Java libraries or modules that your project needs to run correctly. These could be frameworks, utility libraries, or other modules that your project uses. In Maven, these dependencies are managed and configured in the pom.xml file.

3.1 Adding Dependencies

Adding dependencies to your Maven project involves specifying them in your pom.xml file. Let's explore this process with an example of adding the IronPDF library, which is a popular Java library for PDF generation and manipulation using HTML to PDF.

Steps to Add a Dependency

  1. In the IntelliJ IDEA, locate and open your pom.xml file. It's typically found in the root directory of your project and listed in the Project tool window.
  2. In the pom.xml file, look for the <dependencies> section. This tag encapsulates all the dependencies your project requires.
  3. Inside <dependencies>, add a new <dependency> block. In this block, specify the groupId, artifactId, and version of the dependency you wish to add.

    For instance, to add IronPDF as a dependency, your pom.xml should include:

  4. After you've added the required information, save your pom.xml file. IntelliJ IDEA, coupled with Maven, will automatically recognize the changes and prompt you to import the updates. Accept this, and Maven will download and store the specified dependency in your local Maven repository.

3.2 Managing Dependencies

Managing dependencies in Maven is straightforward. You add, update, or remove dependencies by modifying the <dependencies> section of the pom.xml file.

  • Adding a new dependency: Follow the steps outlined above.
  • Updating a dependency: Change the version in the relevant <dependency> block and save the pom.xml file. Maven will then download the new version and update the project accordingly.
  • Removing a dependency: Simply remove the corresponding <dependency> block and save the pom.xml file. Maven will update the project and the dependency will no longer be available.

Remember, whenever you modify the pom.xml file, always import the changes for them to take effect. Through this process, Maven makes it straightforward to manage dependencies, allowing developers to focus more on coding and less on project configuration.

4. Exploring the Maven Tool Window and Goals

In IntelliJ IDEA, the Maven tool window is a practical feature that allows you to manage and execute Maven commands. With its help, you can effectively oversee various aspects of your Maven project without needing to remember or type complex Maven commands.

4.1 Opening the Maven Tool Window

To access this feature-rich tool window:

  1. Navigate to the View menu in the IntelliJ IDEA IDE.
  2. Select Tool Windows from the dropdown menu.
  3. From the list that appears, click on Maven.

Upon completion of these steps, you'll notice the Maven tool window appearing on the right side of the IDE.

4.2 Executing Maven Goals

Maven Goals represent tasks that can be carried out on your project. Examples of such goals are clean, compile, test, and install.

Intellij Maven Guide (How It Works With Java PDF Library): Figure 4 - Goals

To execute a Maven goal:

  1. Locate the Maven tool window and expand the Lifecycle section. This section houses the most common goals.
  2. Right-click on the goal you want to execute, say compile, and select Run Maven Build. IntelliJ IDEA will then execute the selected goal.

5. Compiling and Running Your Maven Project

With your Maven project set up, and the essential Maven goals understood, let's move to compiling and running your project.

5.1 Compiling the Project

Maven's compile goal is responsible for transforming your Java files (.java) into a format that the Java Virtual Machine (JVM) can execute (.class files). Here's how to do it:

  1. Go to the Maven tool window and expand the Lifecycle section.
  2. Double-click on compile. Maven will now process your .java files, compiling them into .class files and storing them in the target/classes directory.

5.2 Running the Project

Once the project has been compiled, we can run it:

  1. In the project's tool window, find the root directory of your project.
  2. Right-click on it and navigate to Run > Main. This action will start the execution of your project.

Note: The option Main can vary based on your project setup. It refers to the main class serving as the entry point of your application.

6. Importing and Updating Maven Project

In the course of working with Maven projects, it's common to modify the pom.xml, like adding or removing a dependency. When you make such modifications, IntelliJ IDEA will prompt you to import the changes. You can also set your IDE to automatically import changes to keep everything synced.

6.1 Manually Importing Changes

If you prefer to manually control when your project should reflect the changes, you can:

  1. Navigate to the Maven tool window.
  2. Locate and click on the Reimport All Maven Projects button (icon with two circular arrows). This action will refresh your project based on the latest pom.xml.

6.2 Enabling Auto-Import

If you'd rather have your changes automatically reflected:

  1. Go to File > Settings (or IntelliJ IDEA > Preferences for macOS).
  2. From the settings, navigate to Build, Execution, Deployment > Build Tools > Maven > Importing.
  3. Check the Enable auto-import box and click OK.

With auto-import enabled, every change in your pom.xml will trigger an automatic import, keeping your project updated. This feature, especially in large projects, can help in maintaining consistency and avoiding manual repetitive tasks.


We've now covered the basics of working with Maven projects in IntelliJ IDEA. Maven is a powerful tool for managing your Java project's structure, dependencies, and build process. Combine that with IntelliJ IDEA, and you get a robust environment that can manage complex applications with ease.

If you're interested in using IronPDF, it's worth noting that they offer a free trial. This allows you to explore and understand its capabilities thoroughly before making a purchasing decision. If you decide to proceed with it, licenses start from $749.

How to Preview PDF Files in Java
How to Parse PDFs in Java (Developer Tutorial)

Ready to get started? Version: 2024.3 just released

Free Maven Download View Licenses >