# WSL2

> **TL;DR**
> Local client OS: Windows
>
>
>
> Remote host OS: WSL [Linux distributions](https://jb.gg/clion-wsl)
>
>
>
> Sources location: local machine
>
>
>
> Project model: [CMake](quick-cmake-tutorial.html) / [Makefile](makefiles-support.html) / [Compilation database](compilation-database.html)

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

With WSL toolchain set up for your project, you can build using a toolchain from Linux, and run/debug on WSL, without leaving CLion running on your Windows machine.

> **Note:**
> You don't need to install or run CLion inside WSL.

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

3. Set up the Linux distribution environment:

Install cmake, gcc, or/and clang (and optionally build-essentials package), as follows:

```CONSOLE
sudo apt-get update
sudo apt-get install cmake gcc clang gdb build-essential
```

Procedure: Configure a WSL toolchain for your project

1. In CLion, go to `Settings | Build, Execution, Deployment | Toolchains`.

2. Click ![plus icon](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) to create a new toolchain and select WSL.

3. In the  Toolset field, select one of the available WSL distributions. The list includes the distributions detected by `wsl.exe --list`, which includes the imported ones.

> **Note:**
> If CLion cannot find your WSL executable, the reason might be the [WSL issue](https://github.com/Microsoft/WSL/issues/2592) fixed in Windows 10 version 1803. Try updating your system to version 1803 or later.

![WSL toolchain](https://resources.jetbrains.com/help/img/idea/2026.2/cl_wsl_new_toolchain.png)

Wait for all the tools to be detected and save the settings.

> **Tip:**
> You can configure CLion to execute WSL commands in login (-l) shell. For more information, refer to [this page](advanced-settings.html#advanced-wsl).

4. Now to start using the toolchain, do the following:

CMake:

1. Set the WSL toolchain as default (move it to the top of the list) or [create an associated CMake profile](remote-projects-support.html#CMakeProfile).

2.  [Build](build-actions.html), [run](running-applications.html), and [debug](debugging-code.html) as usual.

> **Tip:**
> In order to run Valgrind on WSL, make sure to select the CMake profile associated with the WSL toolchain. For more information, refer to [this instruction](memory-profiling-with-valgrind.html#valgrind-wsl).

Makefile:

1. Switch to the WSL toolchain in `Settings | Build, Execution, Deployment | Makefile`.

2. Call `Tools | Makefile | Clean and Reload Makefile Project`.

3. In the [Native Application](makefiles-support.html#create-makefile-config) configuration, point Executable to the binary using the `\mnt\..` notation (for example, `\mnt\c\Users\jetbrains\CLionProjects\SimpleMakefile\runme`).

> **Note:**
> See [WSL specifics when working with Makefile projects](makefiles-support.html#wsl-notes).

## See also

### How tos

[Remote development overview](remote-development.html)

### Getting Started

[Quick Tutorial: Configuring CLion on Windows](quick-tutorial-on-configuring-clion-on-windows.html)

### External Links

[CLion Debugging Beyond the Basics - Part 3 - Beyond Local](https://blog.jetbrains.com/clion/2021/05/clion-debugging-beyond-the-basics-part-3-beyond-local) [Webinar Recording: Remote Development with CLion](https://blog.jetbrains.com/clion/2019/03/webinar-recording-remote-development-with-clion)