← Back to DevBytes
Developer Tutorial July 12, 2026 15 min read

IntelliJ IDEA Project Management: Complete Guide

Understanding IntelliJ IDEA Project Management

IntelliJ IDEA organizes your work around the concept of a project. A project is a top-level organizational unit that groups together all the source files, libraries, tool configurations, build scripts, and settings needed to develop a software application. Unlike some editors that simply open a directory, IntelliJ IDEA treats a project as a structured entity with a formal configuration model.

At the heart of project management lies the .idea directory, which stores XML-based configuration files. These files define everything from the project name and SDK settings to run configurations and version control mappings. Understanding how to manage this structure effectively is essential for any developer working with IntelliJ IDEA across solo projects or large team environments.

Why Project Management Matters

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Proper project management in IntelliJ IDEA delivers several critical benefits:

Project Structure Overview

When you create or open a project in IntelliJ IDEA, the IDE establishes a hierarchy of configuration elements. The key components are:

The physical representation of these settings lives primarily in the .idea folder and, for shared settings, in a dedicated .idea subfolder that you may choose to commit to version control.

Key Configuration Files Inside .idea

project-root/
├── .idea/
│   ├── misc.xml                 # General project settings
│   ├── modules.xml              # Module registry
│   ├── vcs.xml                  # Version control mappings
│   ├── encodings.xml            # File encoding settings
│   ├── compiler.xml             # Compiler settings per module
│   ├── workspace.xml            # Per-developer workspace state (DO NOT COMMIT)
│   ├── codeStyles/
│   │   └── Project.xml          # Shared code style configuration
│   ├── runConfigurations/
│   │   └── MyApp.xml            # Shared run/debug configurations
│   └── inspectionProfiles/
│       └── Project_Default.xml  # Inspection profile settings

The workspace.xml file contains personal settings like open file tabs, window layout, and recent files. This file should never be committed to version control. IntelliJ IDEA provides a built-in .gitignore template that automatically excludes it.

Creating and Configuring a New Project

To create a new project, navigate to File → New → Project. The New Project dialog presents several options depending on your installed plugins and SDKs.

Step-by-Step Project Creation

Here is a practical walkthrough for creating a Java project with Maven:

1. File → New → Project
2. In the left panel, select "Java" (or "New Project" in newer versions)
3. Choose a JDK from the SDK dropdown (or click "Add JDK..." to locate one)
4. Under "Build system," select "Maven"
5. Set the project name: "order-management-system"
6. Set the location: ~/dev/order-management-system
7. Set the JDK language level (e.g., "Java 17")
8. Click "Create"

After creation, the project structure appears in the Project tool window. You can examine the generated pom.xml and the initial module configuration.

Adding Additional Modules

Many real-world applications benefit from a multi-module architecture. To add a new module to an existing project:

1. File → New → Module from Existing Sources... (or right-click project root)
2. Select "Maven" as the module type
3. Specify the module name, e.g., "order-api"
4. Set the parent as the root project
5. Click "Create"

Alternatively, you can create modules manually and update the pom.xml with the appropriate <modules> declaration. IntelliJ IDEA will detect the changes and synchronize the project model.

Configuring Content Roots Programmatically

IntelliJ IDEA stores module content root configuration in XML files. Here is an example from a module's .iml file showing how source folders are marked:

<?xml version="1.0" encoding="UTF-8"?>
<module type="JAVA_MODULE" version="4">
  <component name="NewModuleRootManager">
    <output url="file://$MODULE_DIR$/target/classes" />
    <output-test url="file://$MODULE_DIR$/target/test-classes" />
    <content url="file://$MODULE_DIR$">
      <sourceFolder url="file://$MODULE_DIR$/src/main/java" 
                    isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/resources" 
                    type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/test/java" 
                    isTestSource="true" />
      <excludeFolder url="file://$MODULE_DIR$/target" />
    </content>
    <orderEntry type="inheritedJdk" />
    <orderEntry type="sourceFolder" forTests="false" />
    <orderEntry type="library" name="Maven: org.springframework:spring-core:5.3.21" 
                level="project" />
  </component>
</module>

You can edit these XML files directly, but it is generally safer to let the IDE manage them through the Project Structure dialog (File → Project Structure or Ctrl+Shift+Alt+S).

Working with SDKs and Language Levels

SDK management is a cornerstone of IntelliJ IDEA project configuration. The IDE supports multiple JDK versions simultaneously and allows per-module SDK assignments.

Adding and Configuring JDKs

1. File → Project Structure → Platform Settings → SDKs
2. Click the "+" button → "Add JDK..."
3. Navigate to the JDK installation directory
   (e.g., /usr/lib/jvm/java-17-openjdk on Linux,
    C:\Program Files\Java\jdk-17 on Windows,
    /Library/Java/JavaVirtualMachines/jdk-17.jdk on macOS)
4. Select the directory and click "OK"
5. Optionally rename the SDK (e.g., "OpenJDK 17")

Once added, you can assign this SDK to the project globally or to individual modules in the Project Settings → Project and Modules sections respectively.

Setting Language Level in Code

IntelliJ IDEA respects language level settings that differ from the JDK version. For instance, you can use JDK 17 as the runtime while compiling with Java 11 language features. This is configured in misc.xml and can also be set via Maven compiler plugin properties:

<properties>
  <maven.compiler.source>11</maven.compiler.source>
  <maven.compiler.target>11</maven.compiler.target>
</properties>

IntelliJ IDEA reads these properties from pom.xml and adjusts the project language level automatically during Maven synchronization.

Build System Integration: Maven and Gradle

Modern IntelliJ IDEA project management relies heavily on build system integration. The IDE delegates build operations to Maven or Gradle while maintaining a synchronized internal project model.

Maven Integration Details

When you open a project containing a pom.xml, IntelliJ IDEA offers to import Maven configurations. The Maven tool window (accessible via View → Tool Windows → Maven) displays goals, dependencies, and lifecycle phases.

Key Maven settings that affect IDE behavior:

<settings>
  <proxies>
    <proxy>
      <id>corporate-proxy</id>
      <active>true</active>
      <protocol>https</protocol>
      <host>proxy.example.com</host>
      <port>8080</port>
    </proxy>
  </proxies>
  <mirrors>
    <mirror>
      <id>nexus</id>
      <mirrorOf>central</mirrorOf>
      <url>https://nexus.example.com/repository/maven-central</url>
    </mirror>
  </mirrors>
</settings>

IntelliJ IDEA reads your ~/.m2/settings.xml (or the Gradle user home equivalent) to configure proxy settings and repository mirrors automatically.

Gradle Integration Example

For Gradle projects, IntelliJ IDEA provides similar deep integration. The IDE parses build.gradle or build.gradle.kts and synchronizes dependencies:

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.1.2'
    id 'io.spring.dependency-management' version '1.1.2'
}

group = 'com.example'
version = '1.0.0-SNAPSHOT'

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

repositories {
    mavenCentral()
    maven { url 'https://repo.spring.io/milestone' }
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

After editing this file, IntelliJ IDEA detects changes and prompts for synchronization. You can enable auto-reload in Settings → Build Tools → Gradle to keep the IDE model continuously updated.

Delegating Build Actions

A critical configuration choice is whether to delegate build/run actions to the build system or use the IDE's internal compiler. Navigate to Settings → Build, Execution, Deployment → Build Tools → Maven/Gradle and select "Delegate IDE build/run actions to Maven/Gradle." This ensures consistency between IDE and command-line builds.

Settings (Ctrl+Alt+S)
  → Build, Execution, Deployment
    → Build Tools
      → Maven (or Gradle)
        → Check: "Delegate IDE build/run actions to Maven/Gradle"
        → Runner: Select appropriate JRE and VM options

Run/Debug Configurations

Run configurations define how your application launches within the IDE. These configurations can be temporary (stored in workspace.xml) or permanent (stored as shared files in .idea/runConfigurations/).

Creating a Spring Boot Run Configuration

1. Run → Edit Configurations...
2. Click "+" → "Spring Boot"
3. Name: "OrderService-Local"
4. Main class: Select from the dropdown
   (IntelliJ scans for @SpringBootApplication classes)
5. Program arguments: --spring.profiles.active=local
6. VM options: -Dserver.port=8081 -Xmx512m
7. Environment variables:
   DB_URL=jdbc:postgresql://localhost:5432/orders
   DB_USERNAME=admin
8. Check "Share through VCS" to store in .idea/runConfigurations/
9. Click "Apply" then "OK"

Shared Run Configuration XML

A shared run configuration is stored as XML and can be committed to version control. Here is a sample .idea/runConfigurations/OrderService_Local.xml:

<component name="ProjectRunConfigurationManager">
  <configuration default="false" 
                 name="OrderService-Local" 
                 type="SpringBootApplicationConfigurationType">
    <module name="order-management-system.order-api" />
    <option name="SPRING_BOOT_MAIN_CLASS" 
            value="com.example.order.OrderApiApplication" />
    <option name="VM_PARAMETERS" 
            value="-Dserver.port=8081 -Xmx512m" />
    <option name="PROGRAM_PARAMETERS" 
            value="--spring.profiles.active=local" />
    <envs>
      <env name="DB_URL" 
           value="jdbc:postgresql://localhost:5432/orders" />
      <env name="DB_USERNAME" value="admin" />
    </envs>
    <method v="2">
      <option name="Make" enabled="true" />
    </method>
  </configuration>
</component>

Version Control Integration and Project Sharing

IntelliJ IDEA's project management extends naturally into version control. The IDE integrates with Git, Mercurial, Subversion, and Perforce, mapping project files to repository structures.

Setting Up Version Control

1. VCS → Enable Version Control Integration... (or use the VCS menu)
2. Select "Git" (or your preferred system)
3. The IDE scans for existing .git directories and maps them
4. Configure ignored files via Settings → Version Control → Ignored Files
   Add patterns: .idea/workspace.xml, *.iml (if using Maven/Gradle model),
   target/, build/, out/, *.log

Recommended .gitignore for IntelliJ IDEA Projects

# IntelliJ IDEA - Personal workspace settings
.idea/workspace.xml
.idea/tasks.xml
.idea/shelf/
.idea/dataSources.xml
.idea/dataSources.local.xml

# Build output directories
target/
build/
out/
dist/

# Module files - omit if using Maven/Gradle as primary model
# *.iml

# OS-specific files
.DS_Store
Thumbs.db

# Log files
*.log

The choice to commit .iml files and .idea configuration depends on your team's workflow. For Maven/Gradle-centric projects, many teams commit only the build scripts and let the IDE regenerate project files. For mixed-language projects with complex facet configurations, committing shared .idea files (excluding workspace.xml) can save significant setup time.

Scratch Files and Temporary Experiments

IntelliJ IDEA provides scratch files — temporary, executable files that live outside the project context. These are invaluable for testing code snippets, exploring APIs, or prototyping algorithms without polluting the project structure.

Creating and Using Scratch Files

1. File → New → Scratch File (or Ctrl+Shift+Alt+Insert)
2. Select the language: Java, Kotlin, SQL, etc.
3. Write your experimental code
4. Run it directly using the gutter icon or Ctrl+Shift+F10

// Example scratch file content:
// This lives at ~/.config/JetBrains/IntelliJIdea2024.1/scratches/scratch_1.java

import java.time.*;
import java.time.format.*;

public class Scratch {
    public static void main(String[] args) {
        var now = ZonedDateTime.now(ZoneId.of("UTC"));
        var formatter = DateTimeFormatter.ISO_INSTANT;
        System.out.println("Current UTC timestamp: " + now.format(formatter));
        
        // Quick test of string manipulation
        String input = "order:12345:status:shipped";
        String[] parts = input.split(":");
        for (int i = 0; i < parts.length; i += 2) {
            System.out.printf("Key: %s, Value: %s%n", parts[i], parts[i+1]);
        }
    }
}

Scratch files are stored in the IDE's configuration directory, not in the project folder, making them perfect for throwaway experiments that should never be committed.

Project Templates and File Templates

IntelliJ IDEA allows you to define custom project templates and file templates that enforce consistent coding standards across your team.

Creating a Custom File Template

1. File → Settings → Editor → File and Code Templates
2. Click "+" to add a new template
3. Name: "Spring REST Controller"
4. Extension: java
5. Template content:

#if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")
package ${PACKAGE_NAME};
#end

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;

/**
 * ${NAME} - Generated on ${DATE} at ${TIME}
 * @author ${USER}
 */
@RestController
@RequestMapping("/api/${CLASS_NAME_PREFIX}")
public class ${NAME} {

    @GetMapping
    public ResponseEntity<String> index() {
        return ResponseEntity.ok("${NAME} is operational");
    }

    // TODO: Implement additional endpoints
}

This template uses built-in variables like ${PACKAGE_NAME}, ${NAME}, ${DATE}, and ${USER}. When you create a new file using this template, the IDE populates these variables automatically.

Custom Project Template for Microservices

For organizations building multiple microservices, creating a custom project template saves enormous time:

1. Create a reference project with all desired settings:
   - Standard directory structure
   - Pre-configured Maven/Gradle with common dependencies
   - Dockerfile template
   - README.md skeleton
   - .env.example file
   - CI configuration (e.g., .github/workflows/)

2. File → Manage Project Templates → Project Settings
3. Click "Create project template"
4. Select the reference project directory
5. Define replaceable parameters (e.g., service-name, port, database-name)
6. Save as "Microservice Template"

# When creating a new project:
# File → New → Project → From Template → "Microservice Template"

Performance Optimization for Large Projects

As projects grow, IntelliJ IDEA's indexing and background processes can consume significant resources. Proper project configuration mitigates these issues.

Excluding Directories from Indexing

1. Right-click a directory in the Project tool window
2. Mark Directory as → Excluded
3. The excluded directory turns red and is removed from indexing

# Common exclusion candidates:
- node_modules/ (for JavaScript/TypeScript projects)
- vendor/ (PHP)
- .venv/ or venv/ (Python virtual environments)
- build/ or target/ (compilation outputs)
- Generated source directories (e.g., src/main/generated/)
- Large test data directories

You can also exclude directories via the Project Structure dialog under Modules → Sources, adding paths to the "Excluded Roots" section.

Managing Dependencies Efficiently

# In Maven, use dependency exclusions to limit transitive dependency resolution:
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <exclusions>
    <exclusion>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-tomcat</artifactId>
    </exclusion>
  </exclusions>
</dependency>

# In Gradle, use the same approach:
dependencies {
    implementation('org.springframework.boot:spring-boot-starter-web') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
    }
}

Reducing unnecessary dependencies shrinks the IDE's classpath index and accelerates code completion, refactoring, and build times.

Power-Save Mode and Indexing Controls

# Activate Power Save Mode to disable background analysis:
# File → Power Save Mode (or use the status bar toggle)

# Or selectively disable inspections:
# Settings → Editor → Inspections → uncheck non-essential categories

# For extremely large monorepos, consider:
# Settings → Appearance & Behavior → System Settings
#   → Increase heap size: -Xmx4096m (in idea.vmoptions)
#   → Enable "Use LC_ALL=en_US.UTF-8" for consistent file handling

Sharing Project Settings Across Teams

Team-wide consistency requires deliberate decisions about which configuration files to share and how to manage differences between environments.

The Default Settings Approach

IntelliJ IDEA supports "Default Settings" that apply to all new projects. Configure these once and export them for your team:

1. File → New Projects Setup → Structure for New Projects
2. Configure:
   - SDK: Select the team-standard JDK
   - Language level: Match production Java version
   - Code style: Import team code style XML
   - Inspections: Import team inspection profile

3. Export settings:
   File → Manage IDE Settings → Export Settings...
   Select: Code style, Inspections, File templates, Keymaps
   Save to: team-ide-settings.zip

4. Team members import via:
   File → Manage IDE Settings → Import Settings...

Using Checkstyle and EditorConfig

For even stronger consistency, combine IDE settings with build-time enforcement:

# .editorconfig in project root — honored by IntelliJ IDEA automatically
root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

[*.{java,kt,xml}]
indent_size = 4

[*.{js,json,css,html}]
indent_size = 2

IntelliJ IDEA reads .editorconfig files natively and adjusts editor settings on the fly. Pair this with a Maven Checkstyle plugin to enforce rules at build time.

Shared Run Configurations in CI/CD

When your .idea/runConfigurations/ directory contains shared configurations, you can reference them in CI pipelines using IntelliJ IDEA's command-line launcher:

# Run a shared configuration from CI (Linux/macOS)
./gradlew bootRun -Dspring.profiles.active=ci

# Or use the IDEA command-line runner if installed:
# idea64.exe run --config "OrderService-Local" --project "path/to/project"

# Alternative: Extract the configuration logic into a script
# that mirrors the run configuration parameters:
java -Xmx512m \
     -Dserver.port=8081 \
     -Dspring.profiles.active=ci \
     -DDB_URL=jdbc:postgresql://ci-db:5432/orders \
     -jar order-api/target/order-api-1.0.0.jar

Advanced Module Strategies

For large-scale applications, IntelliJ IDEA's module system supports sophisticated architectural patterns.

Multi-Module Maven Project Example

# Parent pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>platform-parent</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>
  
  <modules>
    <module>platform-core</module>
    <module>platform-data</module>
    <module>platform-api</module>
    <module>platform-ui</module>
  </modules>

  <properties>
    <java.version>17</java.version>
    <spring.version>3.1.2</spring.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-dependencies</artifactId>
        <version>${spring.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

IntelliJ IDEA automatically detects the module hierarchy from the <modules> declaration. Each sub-module appears as a separate module in the Project tool window with its own dependencies and content roots.

Unloaded Modules for Ultra-Large Projects

For monorepos with dozens or hundreds of modules, IntelliJ IDEA supports "unloading" modules to reduce memory footprint:

1. Right-click a module in the Maven/Gradle tool window
2. Select "Unload Module"
3. The module becomes greyed out — its sources are excluded from indexing
4. To reload: right-click → "Load Module"

# Alternatively, configure in .idea/misc.xml:
<component name="UnloadedModules">
  <module name="legacy-integration-tests" />
  <module name="experimental-features" />
</component>

This feature dramatically improves IDE responsiveness in large codebases where you only need to work on a subset of modules at any given time.

Best Practices Summary

Conclusion

Mastering IntelliJ IDEA project management transforms the IDE from a simple code editor into a powerful, team-aligned development platform. By understanding the interplay between project files, modules, SDKs, build systems, and version control, you create a development environment that minimizes friction and maximizes productivity. The investment in proper configuration — from shared run configurations and custom templates to performance-tuned indexing and EditorConfig enforcement — pays dividends every day through faster builds, consistent code quality, and seamless team collaboration. Whether you are working on a small personal project or coordinating a large microservices architecture, the practices outlined in this guide provide a foundation for efficient, maintainable, and scalable project management in IntelliJ IDEA.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles