IntelliJ IDEA 2018.3 Help

Working with modules

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 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 (the .iml file) is used for keeping module configuration, including content or source roots, dependencies, framework-specific settings in facets, and so on.

Configure content roots

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.

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 directory in IntelliJ IDEA is marked with the Directory icon.

Add a new content root

  1. From the main menu, select File | Project Structure(Ctrl+Shift+Alt+S) and click Project Settings | Modules.

  2. Select the necessary module and then open the Sources tab in the right-hand part of the dialog.

  3. Click Add Content Root and specify the folder that you want to add as a new content root. Click OK

    Adding a new content root

To remove a content root, click the Unmark root button. IntelliJ IDEA marks the selected root as a regular folder; the folder itself and its contents won't be deleted.

Folder categories

Folders within content roots can be assigned to several categories.

Sources root

Sources Root

Contains production code that should be compiled

Generated Sources Root

Generated Sources Root

The IDE considers that files in the Generated Sources root folder are generated automatically rather than written manually, and can be regenerated.

Test Sources Root

Test Sources Root

These folders keep code related to testing separately from production code. Compilation results for sources and test sources are normally placed into different folders.

Generated Test Sources Root

Generated Test Sources Root

The IDE considers that files in this folder are generated automatically rather than written manually, and can be regenerated.

Resources Root

Resources Root

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

Test Resources Root

Test Resources Root

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



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.

Load Path Root

Load Path Root

(Ruby only) The load path is the path where the require and the load statements look for files.

Configure folder categories

  1. Right-click a folder in the Project tool window.

  2. Select Mark Directory as from the context menu.

  3. Select the necessary category.

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

To restore the previous category of a 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.

Exclude files

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

To exclude a file, you need to mark it as a plain 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.

Exclude files and folders by name patterns

In some cases, excluding files or folders one by one is not convenient. For example, this may be inconvenient 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 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. Go 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 this 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.

Assign 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 icons modules setPackagePrefixRollover next to Source Folders or Test Source Folders.

  4. Specify the package prefix and click OK.

    package prefix

Change 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 Prefix 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 image

Group 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 can give them fully qualified names. For example, if you want to group all CDI modules, you can add the cdi. prefix to their names.

  1. Open the Project Structure dialog (Ctrl+Shift+Alt+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.

qualified names

Note that if you've configured manual module groups, you will be able to continue working with them, but qualified names won't be available. To enable qualified names, go to File | Convert Module Groups to Qualified Names. In the next dialog, you can review new module names and adjust them if necessary.

Convert Module Groups to Qualified Names dialog

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.

Add a new dependency

  1. Go to File | Project Structure or press Ctrl+Shift+Alt+S.

  2. Select Modules | Dependencies.

  3. Click artwork studio icons common add or press Alt+Insert, and 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.

Remove a dependency

  • To remove a dependency, select it and then click icons general remove svg 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 context menu.

Specify a dependency scope

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

  1. Go 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: required to build, test, and run a project (the default scope).

    • Test: required to compile and run unit tests.

    • Runtime: part of the classpath to test and run a project.

    • Provided: 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.

Analyze 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. Go 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.

You can analyze several dependencies one by one without closing the dialog. The result of each analysis will be opened in a separate tab of the tool window. After you analyze all necessary dependencies, you can close the Project Structure dialog and view results.

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

Sort 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 classes to resolve the corresponding references. At runtime, this list defines the order in which the JVM searches for the classes.

You can sort dependencies by their names and scopes. You can also use the icons actions previousOccurence svg and icons actions nextOccurence svg buttons to move the items up and down the list.

Last modified: 1 February 2019