WSL

WSL (WSL 2) – Windows Subsystem for Linux – is a compatibility layer for running Linux binary executables natively on Windows 10 and later. Currently, it supports several Linux distributions, such as Ubuntu, OpenSUSE, and SLES.

IntelliJ IDEA lets you create and open projects in the WSL file system, run, and debug applications in the WSL environment. You can also use local Windows-based projects and run the applications remotely in WSL with the run targets feature.

Configure WSL

Download and install a WSL distribution (for instance, Ubuntu) from Microsoft Store.
For this step, be sure to use at least Windows 10 or later with the latest “Fall Creators Update” (minimum version 1709, build 16299.15). See the official guide Install the Windows Subsystem for Linux for instructions.
To work with WSL 2, your Windows version should be 10 build 18917 or later. Follow these instructions to switch the distributive.
Note that IntelliJ IDEA does not support legacy WSL, which you may have installed before upgrading your system to the build 16299.15 or later of Windows 10. In this case, you need to update your WSL distribution.
Run the Linux distribution.
Upon the first launch, the system may prompt you to enable the Windows optional feature. In this case, you need to do the following:
- Open Windows PowerShell as Administrator and run
  Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
- Restart your computer.
If you are using Linux distribution other than Ubuntu, ensure that the distribution has the iproute2 package installed or install it manually once the WSL instance is deployed.

You can create a project and store it in the WSL environment, open one from the WSL file system, and develop your projects further in WSL.

Create a new project in the WSL file system

Install and run IntelliJ IDEA locally on Windows as you normally would.
On the welcome screen, click New Project.
On the page that opens, select the following options:
- Name: type the name of your project.
- Create Git repository: select this checkbox if you want to add your project to Git.
- Location: specify the location of your new project on WSL.
  The syntax of the path to a project is as follows:
  \\wsl.localhost\DistributionName\home\UserName\ProjectName
  DistributionName is the name of the Linux distribution, UserName is the name of your user directory.
  Check the following example: \\wsl.localhost\Ubuntu\home\test\MyProject.
- Build system: specify a build tool for your project.
- JDK: specify your project SDK located on WSL.
- Add sample code: select this option for IntelliJ IDEA to add a simple, runnable code to your project.
- Advanced settings: depending on your project, the settings contain additional options.
Click Create.
IntelliJ IDEA creates a project located in WSL and you can develop and build your project inside the WSL environment without leaving the IDE.

Open a project stored in the WSL file system

In IntelliJ IDEA, you can directly open a project stored in the WSL file system and work with it like with any other project.

Click Open on the Welcome screen or select File | Open from the main menu.
In the dialog that opens, select the folder in the WSL file system that contains the project to open, or type the path to the project location manually.
The path syntax is \\wsl.localhost\DistributionName where DistributionName is the name of your Linux distribution such as Ubuntu, Debian, Arch, and so on.

When you run code in your project, it is run in WSL. If you open the run configuration, note that IntelliJ IDEA refers to WSL as local machine.

The results of the code execution are displayed in the Run tool window.

Use WSL to run a project in the Windows file system

You can create or open your project locally on Windows OS with local JDK and then run your compiled code in WSL using run targets. This might be helpful for the cross-platform development.

Create a run configuration for WSL

In the main menu, click Run | Edit Configurations Alternatively, press Alt+Shift+F10, then 0.
Select one of the supported run/debug configuration types.
From the Run on menu, under the New targets section, select WSL to add a WSL target.
When you add the WSL target, IntelliJ IDEA performs an introspection and automatically adds a path to a remote JDK in WSL, and the JDK version in the New Target: WSL dialog.
If you need to add additional information to the existing WSL target, click Manage targets and in the Run Targets dialog, add the needed information. For example, you can select Maven or Gradle as a runtime. Click OK to save the changes.
In the main menu, go to Run and select the necessary run configuration or press (Shift+F10) to run your code and check the output in the Run tool window.

Firewall configuration

You need to perform the following steps to ensure that the building of a project works properly.

Configure firewall settings

Run the Windows PowerShell as administrator.
Execute the following command to allow connections using WSL:
New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
Use the following command to check the exact interface name such as vEthernet (WSL), vEthernet (WSL2), or something else if you renamed it:
Get-NetAdapter
Then execute the command to renew the firewall rules:
Get-NetFirewallProfile -Name Public | Get-NetFirewallRule | where DisplayName -ILike "IntelliJ IDEA*" | Disable-NetFirewallRule
If you are using another IDE, replace IntelliJ IDEA* with its name.
Now start the debugger session. When the Windows Firewall popup appears, select the Public networks checkbox.

29 July 2025