The Visual Studio Code 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. Show
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 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 startedNote: After reviewing this topic, you can get started with the introductory WSL tutorial. InstallationTo get started, you need to:
Open a remote folder or workspaceFrom the WSL terminalOpening a folder inside the Windows Subsystem for Linux in VS Code is very similar to opening up a Windows folder from the command prompt or PowerShell.
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. From VS CodeAlternatively, you can open a WSL window directly from VS Code:
If you already have a folder open, you can also use the WSL: Reopen Folder in WSL command. You will be prompted which distro to use. If you are in a WSL window and want to open the current input in a local window, use WSL: Reopen in Windows. From the Windows command promptTo open a WSL window directly from a Windows prompt use the
for example: We need to do some guessing on whether the input path is a file or a folder. If it has a file extension, it is considered a file. To force that a folder is opened, add slash to the path or use:
To force that a file is opened add
Working with GitIf you are working with the same repository in WSL and Windows, be sure to set up consistent line endings. See tips and tricks for details. You can also avoid passwords by configuring WSL to use the Windows Git credential manager. See tips and tricks for details. Managing extensionsVS 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.
Local extensions that actually need to run remotely will appear dimmed and disabled in the Local - Installed category. Select Install to install an extension on your remote host. You can also install all locally installed extensions inside WSL by going to the Extensions view and selecting Install Local Extensions in WSL: {Name} using the cloud button at the right of the Local - Installed title bar. This will display a dropdown where you can select which locally installed extensions to install in your WSL instance. Opening a terminal in WSLOpening 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 Debugging in WSLOnce 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 See the debugging documentation for details on configuring VS Code's debugging features in WSL specific settingsVS 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. Advanced: Environment setup scriptWhen VS Code Remote is started in WSL, no shell startup scripts are run. This was done to avoid issues with startup scripts that are tuned for shells. If you want to run additional commands or modify the environment this can be done in a setup script The script needs to be a valid Bourne shell script. Be aware that an invalid script will prevent the server from starting up. If you end up with a script that prevents the server from starting, you will have to use a regular WSL shell and delete or rename the setup script. Check the WSL log (WSL: Show Log) for output and errors. Advanced: Opening a WSL 2 folder in a containerIf you are using WSL 2 and Docker Desktop's WSL 2 back-end, you can use the Dev Containers extension to work with source code stored inside WSL! Just follow these steps:
See the Dev Containers documentation for more information. Known limitationsThis 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. I see EACCESS: permission denied error trying to rename a folder in the open workspace in WSL 1That's a known problem with the WSL file system implementation (Microsoft/WSL#3395, Microsoft/WSL#1956) caused by the file watcher active by VSCode. The issue will only be fixed in WSL 2. To avoid the issue, set For large workspace you want to increase the polling interval: WSL 2 does not have that file watcher problem is also not affected by the new setting. Golang in WSL 1
Node.js in WSL 1
Git limitationsIf 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 Docker Extension limitationsWhile the Docker extension can run both remotely and locally, if it is already installed locally, you will be unable to install on a remote SSH host without first uninstalling it locally. We will address this problem in a future VS Code release. Extension limitationsMany 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. In addition, some extensions installed in an WSL when using an Alpine Linux-based distribution may not work due to Common questionsWhy am I asked to change the default distro?When using WSL: New WSL Window using Distro and running on WSL older than Windows 10, May 2019
Update (version 1903) you will be asked to switch the default distribution as the WSL command can only work on the default distro as it does not support the You can always manually switch the default distro by using wslconfig.exe. For example:
You can see which distributions you have installed using:
I'm seeing an error about a missing library or dependencySome 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 What are the connectivity requirements for the WSL extension?The WSL extension and VS Code Server require outbound HTTPS (port 443) connectivity to:
Some extensions (like C#) download secondary dependencies from All other communication between the server and the VS Code client is accomplished through an random local TCP port. You can find a list of locations VS Code itself needs access to in the network connections article. I'm behind a proxy and have connectivity issuesProxy settings might be missing on either the Windows or the WSL side. When a remote window is opened out of VSCode, the WSL extension tries to download the VSCode server on the Windows side. It therefore uses the Window side proxy configuration:
When the remote VSCode is started from a WSL terminal, the download is done using
Once the server is up and running the proxy settings on the Remote tab are used. Can I force 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 For example, the setting below will force the Docker extension to run locally and Debugger for Chrome extension to run remotely instead of their defaults:
A value of 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
11/2/2022 Does Visual Studio work with WSL?Visual Studio's WSL 2 toolset allows you to use Visual Studio to build and debug C++ code on WSL 2 distros without adding a SSH connection. You can already build and debug C++ code on WSL 1 distros using the native WSL 1 toolset introduced in Visual Studio 2019 version 16.1.
How does WSL terminal integrate with VS Code?Integrated Terminal
Run Terminal > New Terminal (Ctrl+`) to open a new terminal instance. You'll start a new instance of the bash shell in WSL, again from VS Code running on Windows. Tip: In the lower left corner of the Status Bar, you can see that you're connected to your WSL: Ubuntu instance.
How do I connect to WSL in Visual Studio?Install & configure Visual Studio
Now you can connect to the Windows Subsystem for Linux from Visual Studio by going to Tools > Options > Cross Platform > Connection Manager. Click add and enter “localhost” for the hostname and your WSL user/password.
|