IntelliJ IDEA 2023.3 Help

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

  1. 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.

  2. 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.

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

  1. Install the needed JDK to the WSL environment using your favorite SDK manager.

  2. On the welcome screen, click New Project.

  3. On the page that opens, select a type of the project you want to create and from the options on the right, select a project SDK (the JDK configured in WSL). Click Next.

    New Project: project sdk
  4. On the next page, specify the name of your project and project location. The project location for WSL will show the absolute path starting with \\wsl$ to the WSL file system.

    New Project: project name and location

    You can type the path to the project location manually or click the Browse button and choose the folder in the dialog, that opens.

  5. Click Finish.

    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.

  1. Click Open on the Welcome screen or select File | Open from the main menu.

  2. 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 \\wsl$ project location manually.

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.

Run configuration

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

Configure Terminal in WSL

  1. To run Terminal in WSL configuration, open project Settings/Preference (Ctrl+Alt+S) and go to Tools | Terminal.

  2. Specify the command in the Shell path field:

    • wsl.exe to use the default Linux distribution

    • wsl.exe -d <distribution name> to use a specific Linux distribution

    Click OK to save changes.

  3. Switch to the Terminal tool window and type any command to inspect the output.

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

  1. In the main menu, go to Run | Edit Configurations. Alternatively, press Alt+Shift+F10, then 0.

  2. In the Run/Debug Configuration dialog, click the Add button on the toolbar or press Alt+Insert. The list shows the run/debug configuration templates.

  3. Select one of the supported run/debug configuration types.

  4. 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.

    New Target: WSL
  5. 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.

    Run targets dialog
  6. 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.

    Run tool window: WSL output

Firewall configuration

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

Configure firewall settings

  1. Run the Windows PowerShell as administrator.

    Restore firewalls to default
  2. Execute the following command to allow connections using WSL:

    New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
  3. Then execute the command to renew the firewall rules:

    Get-NetFirewallProfile -Name Public | Get-NetFirewallRule | where DisplayName -ILike "IntelliJ IDEA*" | Disable-NetFirewallRule
  4. Now start the debugger session. When the Windows Firewall popup appears, select the Public networks checkbox.

    Allow public networks
Last modified: 11 February 2024