# WSL

> **Warning:**
> To work with Gradle or Maven projects, ensure that Remote Execution Agent: Binary Files is [enabled](managing-plugins.html).

[WSL](https://docs.microsoft.com/en-us/windows/wsl/about) ([WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-index)) – 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](https://docs.microsoft.com/windows/wsl/install-win10#windows-10-fall-creators-update-and-later-install-from-the-microsoft-store), 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](run-targets.html) feature.

Procedure: Configure WSL

1. Download and install a WSL distribution (for instance, Ubuntu) from [Microsoft Store](https://jb.gg/clion-wsl) on your Windows machine.

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](https://docs.microsoft.com/en-us/windows/wsl/install-win10) for instructions.

To work with WSL 2, your Windows version should be 10 build 18917 or later. Follow [these instructions](https://docs.microsoft.com/windows/wsl/wsl2-install#set-a-distro-to-be-backed-by-wsl-2-using-the-command-line) 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 ```SHELL Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux ```

* Restart your computer.

> **Note:**
> If you are using Linux distribution other than Ubuntu, ensure that the distribution has the [iproute2](https://wiki.linuxfoundation.org/networking/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.

Procedure: Create a new project in the WSL file system

1. [Install and run](installation-guide.html) IntelliJ IDEA locally on Windows as you normally would.

2. On the welcome screen, click New Project.

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

![New Project: project sdk](https://resources.jetbrains.com.cn/help/img/idea/2026.2/new_project_wsl.png)

4. Click Create.

![Select project location in WSL](https://resources.jetbrains.com.cn/help/img/idea/2026.2/rm_wsl_create_project_settings.png)

IntelliJ IDEA creates a project located in WSL, and you can develop and build your project inside the WSL environment without leaving the IDE.

Procedure: 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](null) 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 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.

![Open project stored in the WSL file system](https://resources.jetbrains.com.cn/help/img/idea/2026.2/open_project.png)

> **Tip:**
> IntelliJ IDEA supports Git from the Windows Subsystem for Linux 2 (WSL2), which is available in [Windows 10 version 2004](https://devblogs.microsoft.com/commandline/wsl2-will-be-generally-available-in-windows-10-version-2004/).
>
>
>
> If Git is not installed on Windows, IntelliJ IDEA searches for Git in WSL and uses it from there. Also, IntelliJ IDEA automatically switches to Git from WSL for projects that are opened when you use the `\\wsl$` path.
>
>
>
> For more information about working with Git in IntelliJ IDEA, refer to [Git](using-git-integration.html).

Procedure: Configure the project location

You can ensure that any project you create or open uses the appropriate WSL location.

1. Press `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) to open settings and then select `Appearance & Behavior | System Settings`.

2. Under the Project section, in the Default project directory field, specify the appropriate WSL directory and click OK to save the changes.

![Default project directory](https://resources.jetbrains.com.cn/help/img/idea/2026.2/default_project_directory.png)

From now on, whenever you [create](#create_project_for_wsl),[open](#open-a-project-in-wsl), or [clone](set-up-a-git-repository.html#clone-repo) a project, the specified directory is selected by default.

When you [run](running-applications.html) 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](https://resources.jetbrains.com.cn/help/img/idea/2026.2/run_configuration_wsl.png)

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

> **Tip:**
> If you need to work with the terminal, you can do so without any additional configuration for your WSL project.

## Use WSL to run a project in the Windows file system

You can [create](new-project-wizard.html)   or [open](import-project-or-module-wizard.html) your project locally on Windows OS with local JDK and then run your compiled code in WSL using [run targets](run-targets.html). This might be helpful for the cross-platform development.

> **Note:**
> The run target feature is supported in the IntelliJ IDEA Ultimate edition only.

> **Note:**
> You might need to configure [firewall settings](#debugging_system_settings), before you use WSL features in the IDE.

Procedure: Create a run configuration for WSL

1. In the main menu, click `Run | Edit Configurations` Alternatively, press `Alt+Shift+F10` (Windows), `⌃ ⌥ R` (macOS), `⌥ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ R` (macOS System Shortcuts), `Alt+Shift+F10` (XWin), `Alt+Shift+F10` (GNOME), `Alt+Shift+F10` (KDE), `Alt+Shift+F10` (Emacs), `Alt+Shift+F10` (Sublime Text), `⌃ ⌥ R` (Sublime Text (macOS)), `Alt+Shift+F10` (NetBeans), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS)), then `0` (Windows), `0` (macOS), `0` (IntelliJ IDEA Classic (macOS)), `0` (macOS System Shortcuts), `0` (XWin), `0` (GNOME), `0` (KDE), `0` (Emacs), `0` (Sublime Text), `0` (Sublime Text (macOS)), `0` (NetBeans), `0` (Visual Studio), `0` (Visual Studio (macOS)), `0` (Eclipse), `0` (Eclipse (macOS)).

2. Select one of the [supported](run-targets.html#supported-rcs) run/debug configuration types.

3. 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](https://resources.jetbrains.com.cn/help/img/idea/2026.2/new_target_wsl.png)

4. 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](https://resources.jetbrains.com.cn/help/img/idea/2026.2/run_target_dialog.png)

5. In the main menu, go to Run and select the necessary run configuration or press (`Shift+F10` (Windows), `⌃ R` (macOS), `⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ R` (macOS System Shortcuts), `Shift+F10` (XWin), `Shift+F10` (GNOME), `Shift+F10` (KDE), `Shift+F10` (Emacs), `Shift+F10` (Sublime Text), `Shift+F10` (Sublime Text (macOS)), `F6` (NetBeans), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS))) 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.

Procedure: Configure firewall settings

1. Run the Windows PowerShell as Administrator.

![Restore firewalls to default](https://resources.jetbrains.com.cn/help/img/idea/2026.2/wsl_prep_debugging_firewall.png)

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

3. Execute the following command to allow connections using WSL:

```
New-NetFirewallRule -DisplayName "WSL" -Direction Inbound  -InterfaceAlias "vEthernet (WSL)"  -Action Allow
```

4. Then execute the command to renew the firewall rules:

```
Get-NetFirewallProfile -Name Public | Get-NetFirewallRule | where DisplayName -ILike "IntelliJ IDEA*" |
Disable-NetFirewallRule
```

> **Note:**
> If you are using another IDE, replace `IntelliJ IDEA*` with its name.

5. Now [start the debugger session](starting-the-debugger-session.html) . When the Windows Firewall popup appears, select the Public networks checkbox.

![Allow public networks](https://resources.jetbrains.com.cn/help/img/idea/2026.2/windows_security_alert.png)

> **Note:**
> We do not recommend using [WSLg](https://devblogs.microsoft.com/commandline/wslg-architecture) with IntelliJ IDEA. IntelliJ IDEA already provides native WSL integration, which is the preferred approach. To learn how to create a project in WSL, refer to [Create a new project in the WSL file system](#create_project_for_wsl).

## See also