IntelliJ IDEA 2017.3 Help

Working with modules

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

Modules consist of a content root and a module file. 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 (an .iml file) is used for keeping module configuration, including content or source roots, dependencies, framework-specific settings in facets, etc.

Configuring content roots

The content in IntelliJ IDEA is a group of files that contain your source code, build scripts, unit tests and documentation. These files are usually organized in a hierarchy. The top-level folder is called a content root folder or a content root.

Modules normally have one content root. You can add more content roots. For example, this might be useful if pieces of your code are stored in different locations on your computer.

At the same time, modules can exist without content roots. In this case, you can use them as a collection of dependencies for other modules.

The content root folder in IntelliJ IDEA is marked with the moduleFolder or folder icon.

Adding and removing content roots

To add a new content root:

  1. Navigate to File | Project Structure, or press Ctrl+Shift+Alt+S.
  2. Select Modules under the Project Settings section.
  3. Select the necessary module, and then open the Sources tab in the right-hand part of the dialog.
  4. Click Add Content Root.
  5. Specify a folder with source files from which you want to create a new content root, and click OK.
    add content root

To remove a content root:

  1. While on the Sources tab, select the content root that you want to remove, click remove x icon.
  2. Confirm deletion. Note that corresponding folder won't be physically deleted.

Folder categories

Folders within content roots can be assigned to several categories.

  • Source roots root_Source.png

    Production code that should be compiled.

  • Generated source roots rootGeneratedSourceIJ

    If a folder is marked as generated, the IDE will think that files in this folder are generated rather than written manually, and can be regenerated. If you try to save files to this folder, or edit files in it, IntelliJ IDEA will show you a relevant warning.

  • Test source roots root_Test.png

    These folders allow you keep the code related to testing separate from the production code. Compilation results for sources and test sources, normally, are placed into different folders.

  • Generated test source roots rootGeneratedTestSourceIJ

    If a folder is marked as generated, the IDE will think that files in this folder are generated rather than written manually, and can be regenerated. If you try to save files to this folder, or edit files in it, IntelliJ IDEA will show you a relevant warning.

  • Resource roots rootResourceIJ (available only in Java modules)

    Resource files used in your application (images, configuration XML and properties files, etc.). During the build process, resource files are copied to the output folder as is.

  • Load path roots root_Source.png (available only when the Ruby plugin is enabled)

    The load path is the path where the require and load statements look for files.

  • Test resource roots rootTestResourceIJ (available only in Java modules)

    These folders are for resource files associated with your test sources.

  • Excluded roots root Excluded

    Files in excluded folders are ignored by code completion, navigation and inspection. That is why, when you exclude a folder that you don't need at the moment, you can increase the IDE performance.

    Normally, compilation output folders are marked as excluded.

    Apart from excluding the entire folders, you can also exclude specific files.

Configuring folder categories

To assign a folder to a specific category:

  1. Right-click the necessary folder in the directory tree of the Project tool window.
  2. Select Mark Directory as from the shortcut menu.
  3. Select the necessary category.
mark as tests project tool window

This way, you can assign categories to sub-folders as well.

To restore previous category of the folder, right-click this folder again, select Mark Directory as, and then select Unmark as <folder category>. For excluded folders, select Cancel Exclusion.

You can also configure folder categories in Project Structure | Modules | Sources.

Excluding files

If you don't need specific files, but you don't want to completely remove them, you can temporary exclude these files from the project. Excluded files are ignored by code completion, navigation and inspections.

To exclude file, you need to mark it as a plain text text file. You can always return excluded files to their original state.

  1. Right-click the necessary file in the directory tree of the Project tool window.
  2. Select Mark as Plain Text from the menu.

Plain text files are marked with the plain text icon icon in the directory tree.

To revert the changes, right-click the file and select Mark as <file type> from the menu.

Excluding files and folders by name patterns

In some cases, excluding files or folders one by one is not convenient. For example, if your source code files and files that are generated automatically (by a compiler, for instance) are placed in the same directories, and you want to exclude the generated files only. In this case, you can configure one or several name patterns for a specific content root.

If a folder name or a file name located inside the selected content root matches one of the patters, it will be marked as excluded. Objects outside the selected content root won't be affected.

  1. Navigate to File | Project Structure, or press Ctrl+Shift+Alt+S.
  2. Click Modules under the Project Settings section, and then select a module. If there're several content roots in the module, select the one that you want to exclude files or folders from.
  3. In the Exclude files field located at the bottom of the dialog, enter a pattern. For example, enter *.aj to exclude AspectJ files.

    You can configure multiple patters and separate them with the ; (semicolon) symbol.

Assigning a package prefix to Java sources

In Java, you can assign a package prefix to a folder instead of configuring a folder structure manually. A package prefix can be assigned to source folders, generated source folders, test source folders and generated test source folders.

  1. Press Ctrl+Shift+Alt+S to open the Project Structure dialog, and then select Modules.
  2. Select the necessary module, and open the Sources tab.
  3. In the right-hand pane, click rootPrefix next to Source Folders or Test Source Folders.
  4. Specify the package prefix and click OK.
package prefix

Changing the output path for resources

When you're building a project, the resources are copied into the compilation output folder by default. You can specify a different directory within the output folder to place resources.

  1. Press Ctrl+Shift+Alt+S to open the Project Structure dialog.
  2. Select Modules and then select the necessary module.
  3. In the right-hand part of the dialog, select the Sources tab.
  4. In the right-hand pane, under Resource Folders or Test Resource Folders, click rootPrefix to the right of the necessary folder (folder path).
  5. Specify the path relative to the output folder root, and click OK.
    resource properties project structure

Grouping modules

IntelliJ IDEA allows you to logically group modules. If you have a large project with multiple modules, grouping will make it easier to navigate through your project.

To sort out modules, you should give them fully qualified names. Support for qualified names is enabled by default in IntelliJ IDEA of version 2017.3 and higher, so no further configuration is required. For example, if you want to group all CDI modules, you can add the cdi. prefix to their names.

You can use the Flatten Modules shortcut menu option to view modules on the same level.

qualified names

Note that if you've configured manual module groups in a project in IntelliJ IDEA version 2017.2 or lower, you will be able to continue working with them in version 2017.3, but qualified names won't be available.

To enable qualified names, select all modules in the Project tool window, open the shortcut menu and select Move Module to Group | Outside Any Group. After that all manually defined modules groups will be disabled, and you will be able to use qualified names to group modules.

Working with module dependencies

Modules can depend on SDKs, JAR files (libraries) or other modules within a project. When you compile or run your code, the list of module dependencies is used to form the classpath for the compiler or the JVM.

To add a new dependency:

  1. Navigate to File | Project Structure or press Ctrl+Shift+Alt+S.
  2. Select Modules | Dependencies.
  3. Click add or press Alt+Insert, and then select a dependency type:
    • JARs or directories.
    • Library. You can select an existing library or create a new one and then add it to the list of dependencies.
    • Module Dependency.

To remove a dependency, select it and then click delete or press Alt+Delete.

Before removing a dependency you can make sure that it is not used in other modules in the project. To do so, select the necessary dependency and press Alt+F7. You can also use the Find Usages option of the shortcut menu.

Specifying dependency scope

Specifying dependency scope allows you control at which step of the build the dependency should be used.

To configure dependency scope:

  1. Navigate to File | Project Structure or press Ctrl+Shift+Alt+S
  2. Select Modules | Dependencies.
  3. Select the necessary scope from the list in the Scope column:
    • Compile — the default scope. Compile dependencies are needed to build, test, and run a project.
    • Test — test dependencies are needed to compile and run unit tests.
    • Runtime — runtime dependencies are a part of the classpath to test and run a project.
    • Provided — the dependency is used for building and testing a project.

IntelliJ IDEA processes dependencies for test sources differently from other build tools (e.g. Gradle and Maven). If your module (say, module A) depends on another module (module B), IntelliJ IDEA assumes that the test sources in A depend not only on the sources in B but also on its own test sources. Consequently, the test sources of B are also included in the corresponding classpaths.

Sorting dependencies

The order of dependencies is important as IntelliJ IDEA will process them in the same order as they are specified in the list.

During compilation, the order of dependencies defines the order in which the compiler (javac) looks for the classes to resolve the corresponding references. At runtime, this list defines the order in which the JVM searches for the classes.

You can sort the dependencies by their names and scopes. You can also use the arrowUp and arrowDown buttons to move the items up and down in the list.

Analyzing dependencies

If you want to check whether a dependency still exists in your project, and find its exact usages, you can run dependency analysis:

  1. Navigate to File | Project Structure or press Ctrl+Shift+Alt+S.
  2. Select Modules | Dependencies.
  3. Right-click the necessary dependency and select Analyze This Dependency.

IntelliJ IDEA will show you collected dependency usages in the Dependency Viewer tool window. You can analyze several dependencies one by one without closing the dialog. The result of each analysis will be open in a separate tab of the tool window. After you analyze all necessary dependencies, you can close the Project Structure dialog and view results of each dependency analysis.

If IntelliJ IDEA finds no dependency usages in the project, you will be prompted to remove this dependency.

Adding support for frameworks and technologies

For developing framework-specific applications, IntelliJ IDEA features facets. Facets are applied to modules, and allow to configure framework-specific settings.

Adding a facet to a module

IntelliJ IDEA can identify a file or a directory that is typical for a certain framework, and add a the necessary facet for you. Once a framework is detected and added, IntelliJ IDEA will inform you about missing configuration and will suggest necessary actions. For example, to configure facet settings.

If a facet is not detected automatically, you can add it manually:

  1. Navigate to File | Project Structure, or press Ctrl+Shift+Alt+S, and click Facets.
  2. Click add (or press Alt+Insert) and select a framework from the list.
  3. Select a module to which you want to add a facet and configure the facet, if required.

You can also add a facet as you create a new project or a new module.

Excluding frameworks from auto-detection

By default, auto-detection is enabled for all the supported frameworks. You can disable framework auto-detection completely, or exclude individual frameworks from auto-detection.

  1. Open the Project Structure dialog, select Facets, and then select Detection.
  2. Click add (or press Alt+Insert), then select the necessary option. For example, you can disable auto-detection of all frameworks in one directory only.
  3. Deselect the Enable framework detection checkbox to disable auto-detection of all frameworks in the entire project.

Unloading modules

To make the IDE work faster, you can temporary set aside or unload modules that you don't need at the moment. IntelliJ IDEA ignores the unloaded modules when you search through or refactor your code, or compile your project.

When you unload modules, you do it locally — the information about unloaded modules is not shared through version control.

To unload or load modules:

  1. In the Project tool window, right-click a module, and select Load/Unload Modules.
  2. Use the buttons in the middle section of the dialog to manage modules. You can also double-click a module in the dialog to load or unload it.
    Unload modules 2


If modules in your project depend on each other, you may face errors when you unload one or more of them.

For example, if Module 1 depends on Module 2, and you unload Module 2, IntelliJ IDEA won't be able to resolve references to classes in Module 2. Moreover, compilation of Module 1 will probably fail.

To avoid such errors, the IDE analyzes dependencies when you load or unload modules. When you load modules, IntelliJ IDEA will suggest to load all dependencies as well. When you unload modules, the IDE will find all dependent modules and will unload them, too.

projects unloaded problems2

If you unload Module 1, you may not see any errors in code in Module 2, and you will also be able to compile Module 2. However, you may accidentally break compilation of dependant code in Module 1 by making changes in code in Module 2. Since Module 1 is unloaded, you won't be able to see any errors until you load it back and compile.

If you invoke Find Usages or refactoring on a class, field, method, etc. contained in Module 2, the result may be incomplete because the contents of Module 1 are not taken into account. IntelliJ IDEA will inform you about that.

Moreover, the IDE will compile unloaded modules every time you commit changes, and will check that the changes don't affect unloaded modules. See more information in Committing changes with unloaded modules.

projects unloaded problems

Automatically loading and unloading new modules

If your teammates add new modules to the project, you will download them to your computer on the project update. After that, the IDE will analyze dependencies between all modules in the updated project.

If you have unloaded modules, IntelliJ IDEA will load or unload new modules according to the results of the dependency analysis.

If new modules depend on the existing unloaded modules, the new modules will be marked as unloaded. IntelliJ IDEA will ignore them because otherwise you may face errors when you try to compile them.

projects unloaded new unloaded

If existing loaded modules have direct dependencies on new modules, the new modules will be marked as loaded.

projects unloaded new loaded

If existing loaded modules have no dependencies on the newly added modules, the new modules will be marked as unloaded. You can manually mark them as loaded as soon as you need them.

projects unloaded new

Committing changes with unloaded modules

If you have unloaded modules, and you make changes in files that your unloaded modules depend on, compilation of these modules may fail after you load them back.

To avoid compilation failures of unloaded modules, make sure that the Compile affected unloaded modules option is selected in the Commit Changes dialog.

Before committing changed files, IntelliJ IDEA will compile unloaded modules to make sure that the changes don't affect these modules. The IDE will inform you about the detected errors, and will suggest resolving them before the commit.

Last modified: 22 January 2018