Developing in WSL

Note: The Remote Development extensions require Visual Studio Code Insiders.


The Visual Studio Code Remote - WSL extension lets you use the Windows Subsystem for Linux (WSL) as your full-time development environment right from VS Code. You can develop in a Linux-based environment, use Linux specific toolchains and utilities, and run and debug your Linux-based applications all from the comfort of Windows.

The extension runs commands and other extensions directly in WSL so you can edit files located in WSL or the mounted Windows filesystem (for example /mnt/c) without worrying about pathing issues, binary compatibility, or other cross-OS challenges.

WSL Architecture

This lets VS Code provide a local-quality development experience — including full IntelliSense (completions), code navigation, and debugging — regardless of where your code is hosted.

Getting started

Installation

To get started you need to:

  1. Install the Windows Subsystem for Linux along with your preferred Linux distribution. VS Code will use your default distro, so use wslconfig.exe to change your default as needed.

    Note: WSL does have some known limitations for certain types of development that can also affect your VS Code experience.

  2. Install Visual Studio Code Insiders on the Windows side (not in WSL).

    Note: When prompted to Select Additional Tasks during installation, be sure to check the Add to PATH option so you can easily open a folder in WSL using the code-insiders command.

  3. Install the Remote Development extension pack.

  4. Consider adding a .gitattributes file to your repos or disabling automatic line ending conversion for Git on the Windows side by using a command prompt to run: git config --global core.autocrlf input If left enabled, this setting can cause files that you have not edited to appear modified due to line ending differences. See tips and tricks for details.

Open a folder in WSL

Opening a folder inside the Windows Subsystem for Linux in VS Code is very similar to opening up a Windows folder from the command prompt.

  1. Open a WSL terminal window (using the start menu item or by typing wsl from the command prompt).

  2. Navigate to a folder you'd like to open in VS Code (including, but not limited to, Windows filesystem mounts like /mnt/c)

  3. Type code-insiders . in the terminal. When doing this for the first time, you should see VS Code fetching components needed to run in WSL. This should only take short while, and is only needed once.

    Note: If this command does not work, you may not have added VS Code to your path when it was installed. Instead, start VS Code, press F1, select Remote-WSL: New Window, and use the File menu to open your folder.

  4. After a moment, a new VS Code window will appear, and you'll see a notification that VS Code is opening the folder in WSL.

    WSL Starting notification

    VS Code will now continue to configure itself in WSL, and install any VS Code extensions you are running locally inside WSL to optimize performance. VS Code will keep you up to date as it makes progress.

  5. Once finished, you now see a WSL indicator in the bottom left corner, and you'll be able to use VS Code as you would normally!

    WSL Status Bar Item

That's it! Any VS Code operations you perform in this window will be executed in the WSL environment, everything from editing and file operations, to debugging, using terminals, and more.

Managing extensions

VS Code runs extensions in one of two places: locally on the UI / client side, or in WSL. While extensions that affect the VS Code UI, like themes and snippets, are installed locally, most extensions will reside inside WSL.

If you install an extension from the Extensions view, it will automatically be installed in the correct location. Once installed, you can tell where an extension is installed based on the category grouping. There will be Local - Installed category and one for WSL.

Workspace Extension Category

Local Extension Category

Note: If you are an extension author and your extension is not working properly or installs in the wrong place, see Supporting Remote Development for details.

Local extensions that actually need to run remotely will appear Disabled in the Local - Installed category. You can click the Install button to install an extension on your remote host.

Disabled Extensions w/Install Button

Advanced: Forcing an extension to run locally / remotely

Extensions are typically designed and tested to either run locally or remotely, not both. However, if an extension supports it, you can force it to run in a particular location in your settings.json file.

For example, the setting below will force the Docker and Debugger for Chrome extensions to run remotely instead of their local defaults:

"remote.extensionKind": {
    "msjsdiag.debugger-for-chrome": "workspace",
    "peterjausovec.vscode-docker": "workspace"
}

A value of "ui" instead of "workspace" will force the extension to run on the local UI/client side instead. Typically, this should only be used for testing unless otherwise noted in the extension's documentation since it can break extensions. See the article on Supporting Remote Development for details.

Opening a terminal in WSL

Opening a terminal in WSL from VS Code is simple. Once folder is opened in WSL, any terminal window you open in VS Code (Terminal > New Terminal) will automatically run in WSL rather than locally.

You can also use the code-insiders command line from this same terminal window to perform a number of operations such as opening a new file or folder in WSL. Type code-insiders --help to see what options are available from the command line.

Using the code CLI

Debugging in WSL

Once you've opened a folder in WSL, you can use VS Code's debugger in the same way you would when running the application locally. For example, if you select a launch configuration in launch.json and start debugging (F5), the application will start on remote host and attach the debugger to it.

See the debugging documentation for details on configuring VS Code's debugging features in .vscode/launch.json.

WSL specific settings

VS Code's local user settings are also reused when you have opened a folder in WSL. While this keeps your user experience consistent, you may want to vary some of these settings between your local machine and WSL. Fortunately, once you have connected to WSL, you can also set WSL specific settings by running the Preferences: Open Remote Settings command from the Command Palette (F1) or by selecting the Remote tab in the settings editor. These will override any local settings you have in place whenever you open a folder in WSL.

Known limitations

This section contains a list of common know issues with WSL. The intent is not to provide a complete list of issues but to highlight some of the common problems seen with WSL.

See here for a list of active issues related to WSL.

Common limitations in WSL

Issue Existing issues
Non-empty folders in the open workspace can't be renamed Microsoft/WSL#3395, Microsoft/WSL#1956
When installing an extension pack in WSL, extensions may install locally instead of in WSL. Click the Install button for each extension in the Local section of the extension panel to work around the issue. Microsoft/vscode-remote-release#11

In addition, local proxy settings are not reused by VS Code running in WSL, which can prevent extensions from working without adding a global HTTP_PROXY and HTTPS_PROXY environment variable with the appropriate proxy information.

Golang in WSL

Issue Existing issues
Delve debugger doesn't work under WSL go-delve/delve#810, Microsoft/vscode-go#926

Node.js in WSL

Issue Existing issues
NodeJS Error: spawn EACCES (different variants of this error) Microsoft/WSL#3886
Webpack HMR not working Microsoft/WSL#2709
Firebase via node unusably slow only on WSL Microsoft/WSL#2657

Git limitations

If you clone a Git repository using SSH and your SSH key has a passphrase, VS Code's pull and sync features may hang when running remotely. Either use an SSH key without a passphrase, clone using HTTPS, or run git push from the command line to work around the issue.

Docker Extension limitations

The Docker extension is configured to run as a local "UI" extension that runs on the Windows side by default. This enables the extension to work with your local Docker installation when you are developing in WSL or inside a container since the Docker CLI is not available by default in these environments. However, commands invoked from the Docker extension that rely on the Docker command line, for example Docker: Show Logs, fail.

Fortunately, if you've installed the Docker CLI in WSL and configured it to work with your local Docker host, you can install the Docker extension inside WSL to solve this problem. Just add the following to settings.json:

"remote.extensionKind": {
    "peterjausovec.vscode-docker": "workspace"
}

Extension limitations

Many extensions will work in WSL without modification. However, in some cases, certain features may require changes. If you run into an extension issue, see here for a summary of common problems and solutions that you can mention to the extension author when reporting the issue.

Common questions

How do I change the distribution Remote - WSL uses?

The Remote - WSL extension uses your default distribution, which you can change using wslconfig.exe.

For example:

wslconfig /setdefault Ubuntu

You can see which distributions you have installed using:

wslconfig /l

I'm seeing an error about a missing library or dependency

Some extensions rely on libraries not found in the vanilla install of certain WSL Linux distributions. You can add additional libraries into your Linux distribution by using its package manager. For Ubuntu and Debian based distributions, run sudo apt-get install <package> to install the needed libraries. Check the documentation for your extension or the runtime that is mentioned for additional installation details.

What are the connectivity requirements for the VS Code Server when it is running in WSL?

The VS Code Server requires outbound HTTPS (port 443) connectivity to update.code.visualstudio.com and marketplace.visualstudio.com. All other communication between the server and the VS Code client is accomplished through an authenticated, random, local TCP port.

As an extension author, what do I need to do?

The VS Code extension API abstracts away local/remote details so most extensions will work without modification. However, given extensions can use any node module or runtime they want, there are situations where adjustments may need to be made. We recommend you test your extension to be sure that no updates are required. See Supporting Remote Development for details.

Questions or feedback