How to Use VS Code with WSL 2 on Windows

You use VS Code with WSL by installing the WSL extension on your Windows VS Code, then opening a folder from inside your Linux distribution. VS Code runs its UI on Windows while all terminals, language tools, and debugging execute inside WSL.

The result is a native Linux development experience on a Windows machine, no virtual machine setup required.

What you need before starting

• WSL 2 and a Linux distribution. On supported Windows 10 builds or Windows 11, open PowerShell as Administrator and run wsl --install, then restart if prompted. New distributions installed this way use WSL 2 by default. Follow the official WSL installation guide for other distributions or older Windows versions.
• VS Code installed on Windows. Download it from code.visualstudio.com. During installation, check Add to PATH so the code command works from the WSL terminal.
• The WSL extension. Install the Microsoft WSL extension with ID ms-vscode-remote.remote-wsl. If you need several remote workflows, you can install the Remote Development extension pack instead.

Step 1: Open your project from the WSL terminal

Launch your WSL distribution from the Start menu. You will see a Linux terminal.

Navigate to your project folder inside the WSL filesystem and run the VS Code command:

bash

cd ~/projects/my-app
code .

The first time you do this, VS Code downloads and installs the VS Code Server inside WSL. A notification shows the progress. This happens only once.

After a moment, a VS Code window opens. The bottom-left Status Bar shows WSL: Ubuntu (or your distribution name). You are now working inside WSL.

Step 2: Confirm you are in WSL mode

• The green remote indicator in the bottom-left corner shows your distribution name.
• Opening a new terminal (Terminal > New Terminal) gives you a Linux shell.
• The File Explorer shows the Linux filesystem path, not a Windows path.

Everything you do in this window happens inside your Linux distribution.

Step 3: Install extensions for the WSL environment

Extensions work differently in a WSL window. VS Code installs UI extensions like themes, snippets, and keymaps locally on Windows. Language extensions and tools run inside WSL.

Open the Extensions view. You will see two sections:

• Local - Installed: Extensions running on the Windows side. Some may appear dimmed with an Install in WSL button. Click it to install them inside WSL.
• WSL: Ubuntu - Installed: Extensions installed and running inside your Linux distribution.

To install an extension only for WSL, open the Extensions view while connected to WSL and install it normally.

Step 4: Work with your project

• Choose Terminal > New Terminal to open a Linux shell inside WSL.
• Configure language runtimes and Git inside the distribution where the tools run.
• Set a breakpoint and start the appropriate debugger to confirm it uses the WSL runtime.
• Use Linux paths when creating or moving files in the Explorer.

Alternative ways to open a WSL window

If you are already in VS Code on Windows, you can switch to WSL without leaving the editor:

• Open the Command Palette (F1) and run WSL: Connect to WSL (uses the default distribution) or WSL: Connect to WSL using Distro (pick a specific one).
• If you have a folder already open in Windows, run WSL: Reopen Folder in WSL to move it into the WSL environment.

To go back to Windows, run WSL: Reopen in Windows.

Where to store your project files

Keep your project files inside the WSL filesystem under /home/yourname/. This gives you full Linux file system performance. Accessing Windows files from WSL is possible through /mnt/c/, but it is slower for file watching, Git operations, and package installs.

Troubleshooting

code . does nothing or says "command not found". VS Code was not added to your Windows PATH. Reinstall VS Code and make sure Add to PATH is checked. Restart your WSL terminal after installing.

File changes are not detected by watchers (webpack HMR, test runners). You are likely on WSL 1 or your project is on a Windows drive. Upgrade to WSL 2 and move your project to the Linux filesystem.

Git shows every file as modified. Avoid editing the same checkout with both Windows and WSL tools. Review the repository's intended line-ending policy and current Git configuration before changing any setting, then test a single file before applying a wider fix.

Extension does not work inside WSL. Some extensions have native dependencies compiled only for x86_64. ARM Windows devices running WSL may not support all extensions. Check the extension's documentation for Linux requirements.

Next, learn how to use VS Code Remote Tunnels to access your machine from anywhere without SSH, or create a Dev Container for a fully reproducible development environment.