IntelliJ IDEA 2017.2 Help

Maven

Creating a new Maven project

IntelliJ IDEA lets you create a Maven project or add a Maven support to any existing project.

  1. Launch the New Project wizard. If no project is currently opened in IntelliJ IDEA, click Create New Project on the Welcome screen: Otherwise, select File | New | Project from the main menu.
  2. Select Maven from the options on the left.
  3. Specify project's SDK (JDK) or use a default one and an archetype if you want to use a predefined project template (configure your own archetype by clicking Add Archetype).
    Click Next.
  4. On the next page of the wizard, specify the following Maven basic elements that are added to the pom.xml file:
    • GroupId - a package of a new project.
    • ArtifactId - a name of your project.
    • Version - a version of a new project. By default, this field is specified automatically.
    Click Next.
  5. If you are creating a project using a Maven archetype, IntelliJ IDEA displays Maven settings that you can use to set the Maven home directory and Maven repositories. Also, you can check the archetype properties. Click Next.
  6. Specify the name and location settings. Click Finish.

Importing a Maven project

  1. On the main menu, select File | Open.
  2. In the dialog that opens, select the pom.xml of the project you want to import. Click OK.
  3. On the first page of the Import Project wizard, in the Import Project from External model select Maven and click Next.

    (This page is not displayed if you selected the pom.xml.)

  4. Specify Maven settings or use the default selection.
    The default settings are usually sufficient for a project. However, you can select the following (frequently used) options:
    • Search for projects recursively - if you select this option, the sub projects (if any) are located and set up correctly.
    • Import Maven projects automatically - if you select this option, the project is imported automatically every time you make changes to your POM file and you don't need to control manually when to import the changes. However, note that it might take some time to re-import a large project. Also, note that the changes made in the IntelliJ IDEA project (for example, adding a dependency to your project through the Project Structure dialog) will be overwritten on re-import by POM since IntelliJ IDEA considers the POM file as a single source of truth.
    Click Next.
  5. IntelliJ IDEA displays the found projects and you can select the ones you need to import.
    Click Next.
  6. Specify the project's SDK and click Next.
  7. Specify a name and the location of your project.
    Click Finish.

Adding a new Maven module to an existing project

You can add a Maven module to the project in which you are already working.

  1. In the Project tool window, right-click the project folder and select New | Module. Alternatively, on the main menu, select File| New | Module to open the New Module wizard.
  2. If you used main menu to add a module then the process of adding a module is the same as Creating a new Maven project.
    If you are adding sub modules by right-clicking the root folder then the process of adding a new module is shorter. You need to specify the name of your module in the ArtifactId field. The rest of the information is added automatically and you can use either default settings or change them according to your preferences.
    Also, note that Add as module to and Parent fields, by default, display the basic Maven attributes (groupId, artifactId, and version) of the project to which you are trying to add the module. You can click /help/img/idea/2017.2/browseButton.png to change the information displayed.

Configuring a multi-module Maven project

IntelliJ IDEA lets you create a multi-module Maven project. The multi-module project is defined by a parent POM file with several sub modules.

  1. Create a Maven parent project. IntelliJ IDEA creates a standard Maven layout including an src folder.
  2. In the Project tool window, remove the src folder (you would need it for very rare cases for your general project you don't need the src folder for the parent POM).
  3. In the Project tool window, right-click your project (or in the main menu, click File) and select New | Module to add a sub project.
  4. In the New Module wizard following the instructions on how to add a module, specify the necessary information and click Finish.
    The src folder is created automatically and you can open POM and add a packaging that you need. IntelliJ IDEA adds the module to the parent project. IntelliJ IDEA also adds name and the description of the sub project to the parent POM.
    /help/img/idea/2017.2/maven_parent_pom.png
    Note that the packaging in the parent POM is defined as pom since it is an appropriate packaging for the parent project which refers to other sub projects.
    Last, but not least, IntelliJ IDEA adds the description of the parent POM to the sub project's POM.
    /help/img/idea/2017.2/maven_module_pom.png
    You can click /help/img/idea/2017.2/maven_go_to_parent_pom_icon.png in the left gutter to quickly open the parent POM from your sub project.
  5. You can also add dependencies to the parent POM that will be inherited by the sub projects.

    /help/img/idea/2017.2/maven_parent_pom_dependency.png

  6. Open Maven Projects tool window to see that all changes made in the parent POM are reflected in sub projects.
    /help/img/idea/2017.2/maven_global_dependency.png

Converting a regular project into a Maven project

You can open an existing non-Maven project and add a Maven support via IntelliJ IDEA UI.

  1. Open an existing project, for example, a Java project.
  2. In the Project tool window, right-click your project and select Add Framework Support.
  3. In the dialog that opens, select Maven from the options on the left and click OK.
    IntelliJ IDEA adds a default POM to the project and generates the standard Maven layout in Project tool window.
    /help/img/idea/2017.2/maven_support_generated_architecture.png
    IntelliJ IDEA also creates a corresponding structure with Lifecycle and Plugins in the Maven Projects tool window.
  4. Open the generated POM and specify a groupId. The artifactId and version are specified automatically.
    /help/img/idea/2017.2/maven_groupId.png
    Every time you change the POM, IntelliJ IDEA displays a pop-up suggesting to import your changes.
    /help/img/idea/2017.2/maven_popup.png

At this point you can further develop your project using Maven. We recommend you to make all your project changes in POM since IntelliJ IDEA considers pom.xml as a single source of truth.

You can conclude the following optional steps to create an executable JAR.

  1. Click /help/img/idea/2017.2/build.png to build project. IntelliJ IDEA generates target folder. Note that IntelliJ IDEA only compiles sources and doesn't create either JAR file or Manifest file.
  2. Create a Manifest file in the resources directory.
    /help/img/idea/2017.2/manifest_file.png
  3. In your POM specify the Manifest file information, so you can use Maven to generate an executable .jar file.
    /help/img/idea/2017.2/pom_manifest_info.png
  4. In the Maven Projects tool window, in the Lifecycle drop-down list, double-click the install command to generate the .jar file.
    IntelliJ IDEA generates an appropriate information in the target folder and an executable JAR in the Project tool window.
    /help/img/idea/2017.2/maven_jar_file.png
    You can right-click the generated JAR and select Run to execute the file.

If your existing project is larger and contains more than one module, converting such project into a Maven project becomes quite challenging. Since IntelliJ IDEA recognizes project setting only from POM when you convert your project you need to check and adjust the following settings:

  • Annotation settings - they are changed for the modules.
  • Compiler output - it is changed for the modules.
  • Resources settings - they are ignored and overwritten by POM.
  • Module dependencies - they need to be checked.
  • Language and Encoding settings - they are changed for modules.

Also, there is no POM template generated. All dependencies (including module dependencies) need to be manually included into POM.

In this case we recommend that you create an external POM where you describe your project and import your POM as you would import a regular Maven project using File | New | Project from Existing Sources command.

IntelliJ IDEA adds POM to the project and a Maven layout for the existing elements.

/help/img/idea/2017.2/maven_project_layout.png
IntelliJ IDEA also generates the corresponding structure in the Maven Projects tool window.
/help/img/idea/2017.2/maven_tool_window_structure.png

Working with Maven dependencies

IntelliJ IDEA lets manage Maven dependencies in your project. You can add, import Maven dependencies, and view them as diagrams.

Adding a Maven dependency

IntelliJ IDEA lets you add a Maven dependency to your project. We recommend that you specify the dependency inside your POM. Dependencies that you set up manually inside IntelliJ IDEA module settings will be discarded on the next Maven project import.

  1. Open your POM in the editor.
  2. Press Alt+Insert to open the Generate context menu.
  3. From the context menu, select Dependency or Dependency Template for quick search.
  4. In the dialog that opens either search for artifacts or for classes if you switch to the Search for class tab.
    /help/img/idea/2017.2/maven_search_artifact.png
    Click Add. IntelliJ IDEA adds the dependency to your pom.xml.
    /help/img/idea/2017.2/maven_pom_dependency.png
    IntelliJ IDEA also adds the dependency to the Dependencies node in the Maven Projects tool window and to the External Libraries in the Project tool window.
    If the added dependency has its own transitive dependencies, IntelliJ IDEA displays them in both tool windows.
    /help/img/idea/2017.2/maven_dependency_trans.png

Centralizing dependency information

In a multi-module Maven project, the dependency in the parent POM will be inherited by all sub projects. You can use dependencyManagement to consolidate and centralize the management of the dependencies' versions.

  1. Open your POM in the editor.
  2. Press Alt+Insert to open the Generate context menu.
  3. From the context menu, select the Managed Dependency option that will show you the list of the dependencies that are defined in the dependencyManagement section of your parent POM in a multi-module project.
    /help/img/idea/2017.2/maven_pom_dependencyManagement.png
  4. Select the desired dependency and click OK.
    /help/img/idea/2017.2/maven_managed_depen.png
    The dependency is added to the POM. You don't need to specify the version on the dependency it will be taken from the DependencyManagement.
    /help/img/idea/2017.2/maven_dependency_no_version.png
    However, if you want to overwrite the defined version, you need to include version when you add the managed dependency to the POM.
    /help/img/idea/2017.2/maven_version_overwrite.png

Adding a scope for the Maven dependency

You can add a scope for your dependency using POM. In this case IntelliJ IDEA will execute the dependency at the specified phase.

  1. In your POM, in the in dependency description add scope and using the code completion add the name of the scope.
    /help/img/idea/2017.2/maven_scope.png
  2. Import your changes. The name of the scope is displayed in the Maven Projects tool window. In the Project Structure dialog, on the Modules page you can see that the scope of the dependency is also displayed.
    /help/img/idea/2017.2/maven_project_structure_scope.png
    Please note that changing dependency's scope in the Project Structure dialog will not affect the pom.xml file.

You can also add a custom .jar file as a dependency using the Maven scope system when you define your dependency. However, note that this dependency will only be available on your machine and you can use it only for the local deployment.

Working with Maven transitive dependencies

IntelliJ IDEA lets you view transitive dependencies that were pulled in with the added or importded Maven dependency. You can check their versions, chanage them, or exclude those dependencies altogether.

The Maven Projects tool window displays the direct dependency and all its transitive dependencies that were pulled in.

  1. In your project's POM, press Ctrl and hover the mouse over the dependency in question.
    /help/img/idea/2017.2/maven_see_depen_pom.png
  2. Click the dependency to open the dependency POM.
  3. In the dependency POM, view the active dependency, its transitive dependencies and their versions.
    /help/img/idea/2017.2/maven_depen_pom.png
    You can check the origin from which the dependency was pulled in.
    /help/img/idea/2017.2/maven_depen_origin.png

You can exclude a transitive dependency if you want.

  1. Open the dependency POM and find the transitive dependency you want to exclude. Copy groupId and artifactId.
  2. In your project POM, underneath your active dependency, enter exclusions and using code completion paste the copied info of the dependency you want to exclude.
    /help/img/idea/2017.2/maven_depen_exclusion.png
    The dependency also excluded from the Project and Maven Projects tool windows.

Importing Maven dependencies

IntelliJ IDEA lets you import dependencies to your Maven project. When IntelliJ IDEA imports added dependencies, it should parse the dependencies and set up the project automatically.

  • In the Maven Projects tool window, click /help/img/idea/2017.2/settings.png icon to open the Maven | Importing settings and select the Import Maven projects automatically check box. Also, ensure the JDK for importer matches the JDK version you are trying to use.
    In this case the dependencies are updated automatically every time you change the POM.
  • Press /help/img/idea/2017.2/reimport_icon.png in the Maven Projects tool window. In this case you manually trigger the re-import process and the update of dependencies.

If for some reason the dependencies weren't imported correctly, try to perform the following actions:

  • You can try to update Maven indices by updating the remote repository in the Maven | Repositories settings.
    /help/img/idea/2017.2/maven_remote_repo.png
  • You can check your local maven repository in the Maven | Repositories settings and try to updated it.
  • You can check the .jar file of the local .m2 repository to see if it was downloaded correctly.
  • You can check the effective POM to determine which Maven repository was used as an origin of the dependency.
  • You can select the Always update snapshots option in Maven settings. In this case IntelliJ IDEA checks the latest version of the downloaded dependency and updates it accordingly.
    /help/img/idea/2017.2/maven_update_snapshots.png

Viewing Maven dependencies as a diagram

IntelliJ IDEA lets you view and work with Maven dependencies in a diagram format.

  1. In the Maven Projects tool window, right-click the desired sub project and choose Show Dependencies, or Show Dependencies Popup.
    /help/img/idea/2017.2/maven_show_depen_diagram.png
  2. In the diagram window, IntelliJ IDEA displays the sub project and all its dependencies including the transitive ones.
    /help/img/idea/2017.2/maven_diagram.png

You can perform different actions while in the diagram window.

You can change the visibility level and, for example, view dependencies that have a specific scope (compile, test, etc.)

  1. In the diagram window, select the sub project and click /help/img/idea/2017.2/level_visibility_icon.png icon.
  2. From the drop-down list, select the dependency scope you want to see.
    /help/img/idea/2017.2/maven_depen_scope_diagram.png
    IntelliJ IDEA displays only the specified dependency scope.
    /help/img/idea/2017.2/maven_specific_scope_diagram.png

You can easily navigate to POM from the diagram window.

  • Select the desired node, and press F4, or choose Jump to Source on its context menu. The corresponding file opens in the editor.

You can exclude a dependency from the diagram.

  1. Select a dependency in the diagram window.
  2. On the context menu, choose Exclude.
    /help/img/idea/2017.2/maven_exclude_diagram.png
  3. From the drop-down list, select the module where the exclusion definition will be added.
    /help/img/idea/2017.2/maven_exclude_defenition.png
    The selected dependencies will be removed from diagram, and the exclusion section will be added to the corresponding dependency in the module's POM.
    /help/img/idea/2017.2/maven_pom_exclusion.png

Working with Maven goals

IntelliJ IDEA lets you create, debug and manage Maven goals in your project.

Running Maven goals

IntelliJ IDEA lets you run Maven goals using several ways. You can run a Maven goal from a command line , use the context menu in the Maven Projects tool window, or create a run/debug configuration to run one or several Maven goals.

Running a Maven goal from the command line

  1. In the Maven Projects tool window, on the toolbar, click the /help/img/idea/2017.2/maven_goal_icon.png icon.
  2. In the Execute Maven Goal dialog, in the Command line field, start entering the name of your goal. You can see that IntelliJ IDEA displays the list of Maven goals from which you can select the appropriate one. Click Execute.
    /help/img/idea/2017.2/maven_exec_maven_goal.png
  3. IntelliJ IDEA runs the selected goal and displays the result in the Run tool window.
    /help/img/idea/2017.2/maven_run_tool_window.png

Running a Maven goal from the context menu

  1. In the Maven Projects tool window, click Lifecycle to open a list of Maven goals.
  2. Right-click the desired goal and from the context menu select Run 'name of the goal'. IntelliJ IDEA runs the specified goal and adds it to the Run Configurations node.

Running a Maven goal or a set of goals via Run configuration

IntelliJ IDEA lets you create a run configuration for one specific goal or a set of several goals.

  1. In the Maven Projects tool window, click Lifecycle to open a list of Maven goals.
  2. Right-click a goal for which you want to create a Run configuration. (To select several Maven goals, press Ctrl and highlight the desired goals.)
    /help/img/idea/2017.2/maven_several_goals_config.png
  3. From the drop-down list select Create 'goal name'.
    /help/img/idea/2017.2/maven_tool_window_context_menu.png
  4. In the Create Run/Debug Configuration: 'goal name' dialog, specify the goal settings (you can specify any Maven commands and arguments) and click OK.
    /help/img/idea/2017.2/maven_goal_run_debug.png
    IntelliJ IDEA displays the goal under the Run Configurations node.
    /help/img/idea/2017.2/maven_runConfigurations_display.png
  5. Double-click the goal to run it or right-click the goal and from the context menu select Run.

Configuring triggers for Maven goals

IntelliJ IDEA lets you run Maven goals before your project's execution or set other conditions using the goal activation configuration.

  1. In the Maven Projects tool window, click Lifecycle to open a list of goals.
  2. In the list that opens, right-click the goal for which you want to set a trigger.
  3. From the context menu, select an activation phase. For example, Execute Before Build.
    /help/img/idea/2017.2/maven_context_menu_trigger.png

    The name of activation phase is added to the selected goal in the Maven Projects tool window.

    /help/img/idea/2017.2/maven_added_trigger.png

You can also create a run/debug configuration that would depend on a Maven goal.

  1. On the main menu, select Run | Edit Configurations to open the run/debug configuration for your project.
  2. In the Run/Debug Configurations dialog, in the Before Launch section, click the /help/img/idea/2017.2/add.png icon.
  3. In the list that opens, select Run Maven Goal.
    /help/img/idea/2017.2/maven_run_config_run_goal.png
  4. In the Select Maven Goal dialog, specify a project and a goal that you want to execute before launching the project.
    /help/img/idea/2017.2/maven_select_goal.png
  5. Click OK.

Associating Maven goals with keyboard shortcuts

You can associate a Maven goal with a keyboard shortcut and execute goals with a single key-stroke.

  1. In the Maven Projects tool window, right-click the desired goal.
  2. On the context menu, choose Assign Shortcut. The Keymap dialog opens.
  3. In the Keymap dialog, under the Maven node navigate to your goal.
  4. Right-click the goal and from the list that opens, select a type of the shortcut you want to assign.
    /help/img/idea/2017.2/maven_shortcut_keymap.png
  5. In the dialog that opens, depending on the shortcut's type, configure your shortcut and click OK.
    /help/img/idea/2017.2/maven_keyboard_shortcut_dialog.png
    The shortcut is displayed against your goal in the Maven Projects tool window.

While in the Keymap dialog, you can add a new goal to which you want to assign a shortcut.

  1. In the Keymap dialog, under the Maven node, click Choose a phase/goal to assign a shortcut.
  2. In the dialog that opens, select a goal you need and click OK.
    /help/img/idea/2017.2/maven_choose_goal.png
    The goal is added to the list under the Maven node. Now you can configure the shortcut.

Debugging Maven goals

IntelliJ IDEA lets you create a debug configuration for one or several Maven goals or you can select a goal and start a debugging session.

  1. On the main menu, select Run | Edit Configurations to create a Maven run/debug configuration.
  2. In the dialog that opens, on the left side, click /help/img/idea/2017.2/add.png to open the Add new Configuration list.
  3. From the list that opens, select Maven to create a new Maven configuration.
  4. On the right side of the dialog, specify the information, such as a name of your configuration, your project's directory, command line parameters, and profiles. You can leave default settings for the rest. Click OK.
  5. On the main menu, click /help/img/idea/2017.2/debug.png to start your debugging session.

You can also start a debugging session for a single Maven goal or a Maven run configuration that may contain more than one Maven goal in the Maven Projects tool window.

  1. Open the Maven Projects tool window.
  2. Under the Lifecycle node, select a goal for which you want to start a debugging session. (Look for existing Maven run configurations under the Run Configurations node to start a debugging session for the run configuration.)
  3. Right-click the goal and from the context menu select Debug [name of the goal]. IntelliJ IDEA starts a debugging session.

Running tests in Maven projects

IntelliJ IDEA lets you run tests using default IntelliJ IDEA test runner. You can also pass Maven Surefire plugin parameters when you run JUnit or TestNg tests and Maven Failsafe plugin parameters for running integration tests. The Maven surefire plugin is declared in the super POM by default, but you can adjust its settings in your project's POM.

You can create and run tests as you normally would for your Java project. See Testing section.

You can run all your tests using the test Maven goal or use Maven commands to run a single test.

  1. Open the Maven Projects tool window.
  2. Under the Lifecycle node select test. Note that goals specified in the Maven surefire plugin will be activated at this phase and all tests in a project or in a module will be run.

If you want to run just a single test instead of all the tests declared in your project, use the Maven -Dtest='TestName' test command.

  1. Open the Maven Projects tool window.
  2. On the toolbar, click the /help/img/idea/2017.2/maven_goal_icon.png icon.
  3. In the Select Maven Goal dialog, specify a project or a module that contains your test and in the Command line field, enter the -Dtest='TestName' test command. Click Execute.
    /help/img/idea/2017.2/maven_run_one_test.png
    Maven runs the specified test and displays the result in the Run tool window.

Alternatively, you can create a Maven run configuration to run a single test using the same Maven command. The run configuration will be saved under the Run Configurations node.

  1. In the Maven Projects tool window, under the Lifecycle node, right-click the test goal.
  2. From the context menu, select Create 'name of the module/project and name of a goal'.
  3. In the dialog that opens, specify a working directory that contains test you want to run and in the Command line field, specify a phase (specified automatically) and the -Dtest='TestName' test command. Click OK.
    /help/img/idea/2017.2/maven_run_config_for_test.png
  4. Open the Run Configurations node and double-click your configuration to run.
    /help/img/idea/2017.2/maven_saved_config.png
    Maven runs the test and displays the result in the Run tool window.

You can skip running tests, for example, when you want to just compile your project and don't want to wait for Maven to complete the tests' execution.

  1. Click the /help/img/idea/2017.2/settings.png icon in the Maven Projects tool window to open Maven settings and select Runner from the options on the left.
  2. On the Runner page, select Skip tests and click OK.
    /help/img/idea/2017.2/maven_settings_skipTests.png
    IntelliJ IDEA de-activates the test goal under the Lifecycle node.
    /help/img/idea/2017.2/maven_tool_win_skipTest.png
    The appropriate message notifying that tests are skipped is displayed in the Maven Run tool window when you execute other goals.
    /help/img/idea/2017.2/maven_run_tool_win_notify.png

Working with Maven profiles

IntelliJ IDEA lets you use Maven build profiles which can help you customize builds for a particular environment, for example, production or development.

Declaring Maven profiles

IntelliJ IDEA lets you declare profiles explicitly in the POM of your project. Using code completion, you can place a number of different configurations inside profiles tags and override default configurations specified in your POM for Maven plugins, dependencies, repositories, etc.

  1. Open your POM in the editor.
  2. Specify the <profiles> section and declare the profiles.
    /help/img/idea/2017.2/maven_profile_declaration.png
    IntelliJ IDEA displays them in the Profiles list of the Maven Projects tool window.
    /help/img/idea/2017.2/maven_tool_win_declared_profiles.png

Alternatively, you can declare profiles using one of the following ways:

  • You can define them locally in the Maven settings directory %USER_HOME%/.m2/settings.xml.
  • You can define them globally in the global Maven settings ${maven.home}/conf/settings.xml.
  • You can define them in the profile descriptor located in the project's base directory (profiles.xml). Note that this option is not supported in Maven 3.0. Please see Maven 3 compatibility notes.

Activating Maven profiles

When IntelliJ IDEA imports a Maven project, it detects profiles and lets you activate them during importing.

  1. Start importing your Maven project.
  2. In the Import from Maven page where IntelliJ IDEA displays the profiles, activate the ones you need.
    /help/img/idea/2017.2/maven_import_proj_select_profiles.png
  3. Click Next and finish your import.

You can activate a profile manually in the Maven Projects tool window using a -P command or using the Profiles node and the corresponding profiles' check boxes.

  1. Open the Maven Projects tool window.
  2. On the toolbar, click the /help/img/idea/2017.2/maven_goal_icon.png icon.
  3. In the dialog that opens, in the Command line field, enter -P and the name of your profile. If you need to exclude certain profiles, specify ! in front of the name of the profile. The profile will be excluded even if it is activated by default. Click OK.

Alternatively, you can use Profiles node in the Maven Projects tool window to activate profiles.

  1. Open the Maven Projects tool window.
  2. Click the Profiles node to open a list of declared profiles.
  3. Select the appropriate check boxes to activate the profiles you need. You can have several active profiles. When they are activated, their configurations are merged based on the POM profile declaration.

You can also activate profiles automatically according to a range of contextual conditions for example, JDK version, OS name and version, presence or absence of a specific file or property, but you still need to specify all of the parameters inside your POM.

You can make a Maven profile to be activated automatically by default if you declare such profile with the activeByDefault tag in the POM.

/help/img/idea/2017.2/maven_profiles_pom.png
IntelliJ IDEA displays the activeByDefault profile in the Maven Projects tool window with the selected check box that is greyed out.
/help/img/idea/2017.2/maven_proj_tool_win_profiles.png
You can manually de-activate this profile by clicking the check box. Also note that if you manually activate any other profile, the activeByDefault profile will be de-activated.
/help/img/idea/2017.2/maven_tool_win_deactivate_profile.png
When you work with multi-module projects, keep in mind that if you specified the activeByDefault profile in your POM it will be de-activated when you manually activate any other profile even if it is declared in the POM of a different module.

Last modified: 25 July 2017