IntelliJ IDEA 2021.1 Help


In IntelliJ IDEA, a module is an essential part of any project – it's created automatically together with a project. Projects can contain multiple modules – you can add new modules, group them, and unload the modules you don't need at the moment.

Generally, modules consist of one or several content roots and a module file, however, modules can exists without content roots. A content root is a folder where you store your code. Usually, it contains subfolders for source code, unit tests, resource files, and so on. A module file (the .iml file) is used for keeping module configuration.

Modules allow you to combine several technologies and frameworks in one application. In IntelliJ IDEA, you can create several modules for a project and each of them can be responsible for its own framework. For more information, refer to Add frameworks (facets).

Module composition shown on a scheme

IntelliJ IDEA modules vs Java modules

In version 9, Java introduced the Java Platform Module System. IntelliJ IDEA had already had a concept of modules: every IntelliJ IDEA module built its own classpath. With the introduction of the new Java platform module system, there appeared two systems of modularity: the IntelliJ IDEA modules, and the new Java 9 modules that are configured using This documentation section describes IntelliJ IDEA modules.

For more information on Java 9 support in IntelliJ IDEA refer to the Support for Java 9 Modules in IntelliJ IDEA 2017.1 and Java 9 and IntelliJ IDEA blog posts.

Projects with multiple modules

IntelliJ IDEA allows you to have many modules in one project, and they shouldn't be just Java. You can have one module for a Java application and another module for a Ruby on Rails application or for any other supported technology.

An application that consists of a client side and a server side is a good example a two-module project.

Add a new module to your project

  1. Right-click the top-level directory in the Project tool window and select New | Module. The New Module wizard opens.

  2. From the list on the left, select a module type.

  3. In the right-hand part of the dialog, select an SDK that you want to use from the Module SDK list. You can use the project SDK or specify a new one.

  4. In the Additional Libraries and Frameworks section, select additional assets that you want to use in this module.

  5. On the next step, name the module and specify the location of the content root and the .iml file. You can place them within or outside of the project.

  6. Click Finish.

    Adding a new module to a project

Import an existing module

You can import a module to your project by adding the .iml file from another project:

  1. From the main menu, select File | New | Module from Existing Sources.

  2. In the dialog that opens, specify the path the .iml file of the module that you want to import, and click Open.

    By doing so, you are attaching another module to the project without physically moving any files. If you don't need the modules to be located in one folder, the module import is finished, and you can start working with the project normally.

Import a module from existing sources

Use these steps to import a project as a module if the project comes from an external model or if you want to create a module from the existing source code that is not necessarily an exported project.

  1. From the main menu, select File | New | Module from Existing Sources.

  2. Select the directory in which your sources, libraries, and other assets are located and click Open.

  3. In the dialog that opens, select Create module from existing sources if you want to create a new module from the existing source code.

    Otherwise, select Import project from external model, select the external model that the project uses, and follow the steps of the wizard.

Group modules

In IntelliJ IDEA, you can logically group modules. If you have a large project with multiple modules, grouping will make it easier to navigate through your project. Module groups can be nested: a group can contain other subgroups.

Create a new module group (deprecated)

In earlier versions (2017.2 and earlier), IntelliJ IDEA used explicit groups for joining modules together. If you've configured manual module groups, you will be able to continue working with them in later versions of the IDE. Alternatively, you can convert module groups and use qualified names instead.

  1. In the Project tool window (Alt+1 ), select the modules that you want to group.

    You can also do so on the Modules page of the Project Structure dialog (Ctrl+Alt+Shift+S ).

  2. From the context menu, select Move Module to Group | New Top Level Group.

  3. Name the new group and click OK.

    The new group is now created and is marked with the the module group icon.

Select Outside Any Group to exclude the selected module from the group, To This Group to add the module to the group, or To New Subgroup to create a new group in another group.

Convert module groups to qualified names (deprecated)

  1. From the main menu, select File | Convert Module Groups to Qualified Names.

  2. In the next dialog, review the new module names and adjust them if necessary.

  3. Apply the changes and close the dialog.

Group modules by fully qualified names

IntelliJ IDEA 2017.3 and later uses fully qualified names to group modules. For example, if you want to group all CDI modules, add the cdi prefix to their names.

  1. Open the Project Structure dialog Ctrl+Alt+Shift+S and click Modules.

  2. Select the modules you want to group, open the context menu, and click Change Module Names.

  3. Specify a prefix and apply the changes.

    To view all modules on the same level in the Project Structure dialog, use the Flatten Modules context menu option.

    Grouping modules using a prefix
Last modified: 15 June 2021