IntelliJ IDEA Integration

This guide covers configuring IntelliJ IDEA Community Edition to work with WSL2, allowing you to develop Java applications with the full power of IntelliJ whilst your projects and tools run in WSL2.

1. Why IntelliJ with WSL2?

IntelliJ IDEA has native WSL2 support that provides:

  • Direct access to JDK installed in WSL2

  • Maven and Gradle projects work seamlessly

  • Git from WSL2 is automatically detected

  • Run/debug configurations execute inside WSL2

  • Terminal opens in WSL2 context

  • Full debugging support with breakpoints

2. Install IntelliJ IDEA Community Edition

2.1. Download and install

  1. Download IntelliJ IDEA Community Edition from https://www.jetbrains.com/idea/download/

  2. Select Community (free) edition

  3. Run the installer with default settings

  4. Launch IntelliJ IDEA

3. Configure WSL2 integration

3.1. Verify WSL2 detection

  1. Open IntelliJ IDEA

  2. Go to File → Settings (Ctrl+Alt+S)

  3. Navigate to Build, Execution, Deployment → WSL

  4. Verify your Ubuntu distribution is detected

3.2. Configure WSL2 JDK

  1. Open File → Project Structure (Ctrl+Alt+Shift+S)

  2. Go to Platform Settings → SDKs

  3. Click + → Add JDK…​

  4. Navigate to: \\wsl$\Ubuntu\usr\lib\jvm\java-21-openjdk-amd64

  5. Name it descriptively: JDK 21 (WSL2 Ubuntu)

The path \\wsl$\Ubuntu... is the Windows UNC path to access WSL2 files. IntelliJ uses this to access the Linux JDK.

4. Open projects from WSL2

4.1. Opening a project

  1. Click File → Open

  2. In the path field, enter the WSL2 path:

    \\wsl$\Ubuntu\home\<username>\dev\ems\admin-service

  3. IntelliJ automatically detects Maven/Gradle and configures the project

4.2. Set project SDK

  1. Open File → Project Structure (Ctrl+Alt+Shift+S)

  2. Under Project Settings → Project

  3. Set SDK to your WSL2 JDK: JDK 21 (WSL2 Ubuntu)

5. Configure terminal for WSL2

Configure IntelliJ’s terminal to use WSL2:

  1. Open Settings (Ctrl+Alt+S)

  2. Navigate to Tools → Terminal

  3. Set Shell path to: wsl.exe

  4. Or for a specific distribution: wsl.exe -d Ubuntu

Now when you open a terminal in IntelliJ (Alt+F12), it opens a WSL2 Bash session.

6. Configure Windows Firewall

If you encounter connection issues between IntelliJ and WSL2:

Open PowerShell as Administrator and run:

# Allow IntelliJ through firewall for WSL
New-NetFirewallRule -DisplayName "Allow IntelliJ IDEA WSL2" `
    -Direction Inbound -Protocol TCP -Action Allow `
    -RemoteAddress 172.16.0.0/12

7. Eclipse keymap for migrating users

If you’re transitioning from Eclipse, IntelliJ provides a built-in Eclipse keymap:

  1. Open Settings (Ctrl+Alt+S)

  2. Navigate to Keymap

  3. From the dropdown, select Eclipse

  4. Click Apply

7.1. Key shortcuts comparison

Action Eclipse IntelliJ (Eclipse Keymap)

Search everywhere

Ctrl+3

Ctrl+3

Go to class

Ctrl+Shift+T

Ctrl+Shift+T

Go to file

Ctrl+Shift+R

Ctrl+Shift+R

File structure

Ctrl+O

Ctrl+O

Quick fix

Ctrl+1

Ctrl+1

Format code

Ctrl+Shift+F

Ctrl+Shift+F

Organise imports

Ctrl+Shift+O

Ctrl+Shift+O

Rename

Ctrl+Alt+R

Ctrl+Alt+R

Run

Ctrl+Shift+F11

Ctrl+Shift+F11

Debug

Ctrl+F11

Ctrl+F11

Find in files

Ctrl+H

Ctrl+H

Find usages

Ctrl+Shift+G

Ctrl+Shift+G

7.2. Live templates comparison

Purpose Eclipse IntelliJ

Main method

main

psvm

System.out.println

sysout

sout

For-each loop

foreach

iter

Try-catch

try

trycatch

7.3. Recommended plugins for Eclipse users

Install these plugins via File → Settings → Plugins:

  • Key Promoter X - Shows keyboard shortcuts for mouse actions

  • Eclipse Code Formatter - Use your existing Eclipse formatter settings

  • Eclipser - Import Eclipse run configurations

8. Running and debugging

8.1. Run configurations

IntelliJ automatically creates run configurations when you:

  • Click the green play button next to a main method

  • Right-click a test class and select Run

These configurations execute inside WSL2.

8.2. Debugging

  1. Set breakpoints by clicking in the left gutter

  2. Click the debug button (bug icon) or press Shift+F9

  3. The debugger connects to the JVM running in WSL2

  4. All debugging features work normally

8.3. Spring Boot applications

For Spring Boot projects:

  1. Open the main application class

  2. Click the green play button next to @SpringBootApplication

  3. Access the application at http://localhost:<port>;

WSL2’s localhost forwarding allows Windows browsers to access the application.

9. Maven/Gradle integration

9.1. Maven

IntelliJ automatically detects the Maven installation in WSL2:

  • Maven is used from: /usr/share/maven

  • The .m2 repository is at: ~/.m2/repository (in WSL2)

To manually configure:

  1. Open Settings (Ctrl+Alt+S)

  2. Navigate to Build, Execution, Deployment → Build Tools → Maven

  3. Set Maven home path to: \\wsl$\Ubuntu\usr\share\maven

9.2. Gradle

For Gradle projects, IntelliJ uses the wrapper by default, which works correctly in WSL2.

10. Terminology: Eclipse to IntelliJ

Eclipse IntelliJ Notes

Workspace

Project

IntelliJ uses one project per window

Project

Module

Multiple modules can exist in one project

Facet

Facet

Same concept

Library

Library

Same concept

JRE

SDK

IntelliJ supports multiple SDKs

11. Importing Eclipse projects

11.1. Maven/Gradle projects

  1. Click File → Open

  2. Navigate to your project’s pom.xml or build.gradle

  3. IntelliJ auto-detects and configures the project

11.2. Importing Eclipse code style

  1. Export your Eclipse formatter as XML (in Eclipse)

  2. In IntelliJ: Settings → Editor → Code Style → Java

  3. Click the gear icon → Import Scheme → Eclipse XML Profile

  4. Select your exported file

12. Troubleshooting

12.1. IntelliJ cannot connect to WSL2

# Check WSL2 is running
wsl --list --verbose

# Restart WSL2
wsl --shutdown
wsl

12.2. JDK not detected

Ensure the JDK path is correct:

  • Open File Explorer

  • Navigate to \\wsl$\Ubuntu\usr\lib\jvm\

  • Find the exact JDK directory name (e.g., java-21-openjdk-amd64)

  • Use this exact path in IntelliJ’s SDK configuration

12.3. Maven build failures

Check that JAVA_HOME is set in WSL2:

echo $JAVA_HOME
# Should show: /usr/lib/jvm/java-21-openjdk-amd64

# If not set, add to ~/.bashrc
echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc
source ~/.bashrc

13. Next steps

Proceed to Workspace Setup to clone the EMS repositories and set up your development workspace.