# WSL

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/ruby/llms.txt).

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

## Native mode

Starting with version 2026.3, RubyMine opens projects stored in the WSL file system in Native mode. To work with such a project, [open it](#open-a-project-in-wsl) in RubyMine running on Windows, and use [native WSL interpreters](configuring-language-interpreter.html#native_ruby_interpreters) to run Ruby.

In Native mode, RubyMine runs on your local machine and works with a project stored in WSL or in a Dev Container directly. Your code, Ruby installation, gems, and tools stay in the Linux environment. A lightweight agent in the environment handles file access and process execution.

Compared with [Remote Development](remote.html), Native mode works as follows:

* RubyMine does not download or install an IDE backend in the environment.

* The project opens in a regular RubyMine window instead of a separate client. Your local settings, plugins, and keymap apply as usual.

* Linux paths and symbolic links are handled correctly, without converting them to Windows paths.

Compared with legacy remote interpreters, [native interpreters](configuring-language-interpreter.html#native_ruby_interpreters) do not require path mappings and do not copy helper scripts to the environment. RubyMine runs Ruby, Bundler, tests, and other tools directly in the environment.

Remote Development remains the recommended option when your project is located on a remote machine that you connect to over SSH.

Procedure: Enable the Remote Execution Agent plugin

Make sure this plugin is installed and enabled to ensure the proper performance of your IDE.

1. In the Settings dialog (`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` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Meta+Comma` (TextMate), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))), select  Plugins.

2. Start typing the name of the plugin.

3. Do one of the following:

* If the plugin is not installed, click Install. Wait for RubyMine to install the plugin and make sure it is enabled. If not, click Enable.

* If the plugin is installed, find the plugin and make sure it is enabled. If not, click Enable.

The image below shows the plugin in the enabled state.

![Remote Execution Agent plugin](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_execution_agent.png)

4. Apply the changes and close the settings dialog.

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.

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. (Optional) If your Linux distribution doesn't come with `rsync`, you need to install it, for example:

Debian, Ubuntu:

```CONSOLE
apt-get install rsync
```

Fedora:

```CONSOLE
yum install rsync
```

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.

> **Note:**
> Before you create or open a Ruby/Rails project, make sure to set up the [Ruby/Rails development environment.](set-up-a-ruby-development-environment.html)

Procedure: Create a new project in the WSL file system

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

2. On the [Welcome screen](null), click New Project or select `File | New Project` from the main menu.

![Create a project in WSL: Welcome screen](https://resources.jetbrains.com/help/img/idea/2026.3/rm_wsl_create_project_welcome_screen.png)

3. On the page that opens, select the project type and provide details for the following fields:

1.  Name: project name

2. Project location: the location of your project on WSL. You can enter or paste the path directly, or click the Browse button to find the directory using the file browser.

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

3. Interpreter: the Ruby interpreter or the version manager executable installed in WSL.

4. Rails version (If a Rails application type was selected): select a Rails version that you want to use in your project. If the Rails gem is not installed in the selected interpreter or the necessary Rails version is missing, click the + icon in the field. Wait until RubyMine downloads all available Rails versions and select the necessary version from the dropdown. Click OK to continue.

4. Click Create.

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

RubyMine 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 RubyMine, you can directly open a project stored in the WSL file system and work with it like with any other project.

1. Select `File | Open` from the main menu.

2. In the dialog that opens, specify the project location: either insert the path to the folder in the WSL file system or locate it using the file browser.

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 existing project in wsl](https://resources.jetbrains.com/help/img/idea/2026.3/rm_open_existing_project_in_wsl.png)

3. Click OK. RubyMine opens the project in [Native mode](#native_mode).

If this is the first WSL project that you open and you do not have legacy WSL interpreters, RubyMine enables native WSL interpreters and detects Ruby installed in WSL. Otherwise, you can [switch to native interpreters](configuring-language-interpreter.html#enable_native_wsl_interpreters) on the Ruby settings page.

> **Tip:**
> RubyMine 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, RubyMine searches for Git in WSL and uses it from there. Also, RubyMine 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 RubyMine, 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` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Meta+Comma` (TextMate), `Ctrl+Alt+S` (NetBeans), `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/help/img/idea/2026.3/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.

## Tools in WSL

If your project is stored in WSL, path macros return the path in the format that RubyMine uses.

The macro preview shows the same value:

```
\\wsl.localhost\Ubuntu\home\me\index.php
```

.

When you run the tool, RubyMine converts the paths to the format of the environment where the tool runs.

Check the following example:

```
<path>/home/me/index.php</path>.
```

RubyMine selects the environment as follows:

1.  If Program points to a file inside WSL, the tool runs in WSL.

2.  If Program is a command name, such as `node` or `git`, the Working directory defines the environment. If the working directory is inside WSL, the tool runs in WSL, and RubyMine looks for the command in the `PATH` of that WSL distribution.

3. In all other cases, the tool runs on Windows.

> **Warning:**
> If Program is an absolute Windows path, for example `C:\Program Files\nodejs\node.exe`, the tool runs on Windows even if the project and the working directory are in WSL. In this case, the arguments contain paths that exist only in WSL, and the tool fails with errors such as `No such file or directory`. To run the tool in WSL, specify the command name or the path to the executable inside WSL.

RubyMine converts the path in Program, the path in Working directory, and each argument that consists of a path only. Paths inside longer arguments and paths in environment variables stay unchanged. For example, with the `-e "console.log('$FilePath$')"` arguments, the tool receives the path in the `\\wsl.localhost\...` format.

To get the Linux path, pass it as a separate argument and refer to that argument in the command:

```PLAINTEXT
-e "console.log(process.argv[1])" $FilePath$
```

## WSLg

[WSLg](https://devblogs.microsoft.com/commandline/wslg-architecture) lets you run Linux GUI applications and shows their output on the Windows desktop.

We do not recommend running RubyMine through WSLg. RubyMine already provides native WSL integration, which is the preferred approach.

Keep in mind the following:

* WSLg has limitations related to rendering, popups, window management, input methods, and desktop integration.

* We do not provide dedicated support, installation guidance, onboarding, or product-specific fixes for running RubyMine through WSLg.

To learn how to open a project, refer to [Open a project stored in the WSL file system](#open-a-project-in-wsl) or if you want to create the new one, refer to [Create a new project in the WSL file system](#create_project_for_wsl).

