Project import

Project import is how Java and Kotlin by IntelliJ IDEA turns a directory that you open in the editor into a project it can work with. During import, the extension reads the build configuration, resolves dependencies, and builds a project model that includes source roots, modules, and libraries. Code insight features rely on this model and become fully available after the import is complete.

Import runs automatically. As soon as you open a directory that contains a supported build file, the extension imports the project in the background. You do not need to run any commands or trigger the import manually. Once import finishes, Java and Kotlin by IntelliJ IDEA creates and maintains indexes for the workspace, and code insight becomes available.

Java and Kotlin by IntelliJ IDEA detects and imports projects based on the following build systems:

Gradle
Maven
Bazel

When a directory contains a single project with one build system, Java and Kotlin by IntelliJ IDEA recognizes it and imports the project automatically.

Several build systems in a project

When a directory can be imported by more than one build system, for example, a folder that contains both a build.gradle.kts and a pom.xml file, the extension displays a notification where you can choose the build system to use for a single import.

The notification shown when multiple build systems are detected within the workspace

Alternatively, you can describe the project structure in the settings.

Monorepos and multiple projects

A directory does not always map to a single project. It can be a monorepo that holds many projects, or a directory that groups several independent projects. In these cases, the project you want to work with is not necessarily at the workspace root, and importing everything can use a significant amount of memory.

To keep import scoped to what you work on, list the projects to import in the intellij.projects setting. When you open a smaller subdirectory, only the projects it contains are imported, which matches your active working set rather than the entire repository.

Configure which projects to import

To import several projects using different build systems, describe them in the intellij.projects setting, configurable in the settings.json file.

Each entry declares a project type and a path. For Gradle and Maven, path points to the build file (build.gradle.kts or pom.xml); for Bazel, it points to the workspace root directory:

"intellij.projects": [
    { "type": "gradle", "path": "file:///<path-to-project>/build.gradle.kts" },
    { "type": "maven", "path": "file:///<path-to-project>/pom.xml" },
    { "type": "bazel", "path": "file:///<path-to-project>/bazel-workspace/" }
]
        

The path value must be an absolute file:// URI that starts from the filesystem root, which depends on your operating system. Variables such as ${workspaceFolder} and paths relative to the workspace are not expanded in this field.

Entries accept additional options depending on the project type:

project-path (Bazel): Path to the Bazel project file (for example, .bazelproject), relative to the workspace root.
java-home (Maven): Path to the JDK home used to run the import.
env (Maven): Extra environment variables for the import process, as a map of names to values.
system-properties (Maven): JVM system properties for the import process, as a map of names to values.

Indexing limitations

Java and Kotlin by IntelliJ IDEA creates and maintains indexes separately for each workspace.

Reusing indexes: Workspace indexes can be reused across machines if the workspace is available at the same absolute path on both machines.
Concurrent access: Only one Java and Kotlin by IntelliJ IDEA backend can access a workspace at a time. Running multiple backends against the same workspace is not supported.

28 July 2026