Installing Visual Studio Code and WSL gives you two important parts of a modern Windows development environment. The next step is connecting them correctly.
VS Code runs as a Windows desktop application, while WSL provides a Linux environment with its own terminal, file system, and development tools. When the connection is configured properly, you can use the familiar VS Code interface while your project and terminal commands run inside Linux.
This setup is useful for web development, command-line tools, package managers, and AI coding agents that expect a Linux-style environment.
The connection itself is not difficult, but beginners often run into problems because the same project can appear through both Windows and Linux paths. The most important goal of this guide is therefore not only to open WSL in VS Code, but to understand where the project lives and which environment is running your commands.
Version note: Extension names, menus, connection indicators, and installation steps may change between VS Code releases. Before publication, compare version-sensitive instructions with the current official Visual Studio Code documentation for WSL development.
What You Will Learn
By the end of this guide, you should be able to:
- install the official VS Code support for WSL;
- open a Linux project folder in VS Code;
- confirm that VS Code is connected to WSL;
- verify that the integrated terminal is running inside Linux;
- create a consistent project location under your Linux home directory;
- understand the difference between Windows and WSL paths;
- reopen an existing WSL project;
- avoid common mixed-environment problems.
This article assumes that Visual Studio Code and WSL are already installed.
If you have not completed those steps, return to the earlier guides in this series before continuing.
How VS Code and WSL Work Together
VS Code uses a client-and-server model for WSL development.
The visible VS Code window still runs as a Windows desktop application. However, when you connect to WSL, VS Code starts supporting components inside the Linux environment.
That allows Linux-side tools to work with the editor.
A simplified view looks like this:
Windows
├── Visual Studio Code interface
├── Browser
└── WSL connection
└── Linux environment
├── Project files
├── Terminal
├── Git
├── Language tools
└── AI coding tools
This arrangement gives you the convenience of a Windows application while keeping the development environment inside Linux.
When the connection is active, the integrated terminal should use your Linux shell. Extensions that need to run against the project may also be installed inside the WSL environment rather than only on the Windows side.
That distinction becomes important later when we install development tools, Git, GitHub Copilot, and Claude Code.
Install the Official WSL Extension
Open Visual Studio Code on Windows.
Select the Extensions view from the Activity Bar. You can also open it from the View menu.
Search for:
WSL
Look for the official WSL extension published by Microsoft.
Before installing it, confirm:
- the publisher is Microsoft;
- the extension is listed in the current official VS Code WSL documentation;
- the name and logo match the official listing;
- you are not installing an unofficial extension with a similar title.
Depending on the current VS Code distribution, WSL support may also be offered as part of a broader remote development extension package. For a beginner workflow, installing the official WSL extension is normally sufficient.
Select Install.
After installation, VS Code may display a new connection option or remote-development indicator near the lower-left corner of the window.
The exact appearance may vary by version.
Open WSL from Visual Studio Code
There are several ways to connect VS Code to WSL.
The two most useful methods for beginners are:
- opening a WSL window from the VS Code interface;
- opening VS Code from inside the WSL terminal.
Both methods should lead to the same general result: a VS Code window connected to your Linux distribution.
Method 1: Connect from the VS Code Interface
Open the Command Palette.
Search for a command similar to:
WSL: Connect to WSL
If you have more than one Linux distribution installed, you may also see an option to connect to a specific distribution.
Choose the distribution you prepared in the previous guide, such as Ubuntu.
VS Code may open a new window while it installs or starts required support components inside WSL.
The first connection may take longer than later connections.
When the connection is complete, look for an environment indicator near the lower-left corner of the window. It should show that the editor is connected to WSL or to the selected Linux distribution.
Method 2: Open VS Code from the WSL Terminal
Open your Linux distribution from the Windows Start menu.
Move into the projects folder created in the previous guide:
cd ~/projects
Confirm your location:
pwd
The output should resemble:
/home/your-username/projects
Now run:
code .
The code command launches Visual Studio Code.
The period means “the current directory,” so the command asks VS Code to open the folder you are currently in.
A new VS Code window should open and connect to WSL.
If the command works, this is one of the most convenient ways to open a project because it makes the active directory explicit.
What to Do If code . Does Not Work
If the Linux terminal reports that the code command is not found, check the following:
- Visual Studio Code is installed on Windows.
- The official WSL extension is installed.
- VS Code has been opened at least once after the extension installation.
- You are using an actual WSL terminal rather than a remote Linux server.
- VS Code has completed any required WSL support installation.
Try opening VS Code normally and connecting to WSL through the Command Palette first.
After the connection succeeds, close the window and try again from the WSL terminal:
code .
If the command still fails, compare the error message with the current official VS Code WSL troubleshooting documentation before changing system paths manually.
Avoid copying random shell configuration commands from old forum posts. A path workaround written for an earlier VS Code release may no longer be appropriate.
Create a Project Inside WSL
For Linux-oriented development, a clear project location helps prevent confusion.
In the previous article, we created:
~/projects
Inside the WSL terminal, run:
cd ~/projects
Create a new folder for this exercise:
mkdir wsl-vscode-practice
Move into it:
cd wsl-vscode-practice
Confirm the location:
pwd
The result should look similar to:
/home/your-username/projects/wsl-vscode-practice
Open the folder in VS Code:
code .
The Explorer should display wsl-vscode-practice as the root folder.
This project now lives inside the Linux file system, even though you are viewing and editing it through a Windows desktop application.
Verify That VS Code Is Connected to WSL
Do not assume that a folder is open in WSL only because VS Code launched successfully.
Verify the environment.
Check the Connection Indicator
Look near the lower-left corner of the VS Code window.
The current interface should display some indication that the window is connected to WSL or to a Linux distribution.
The exact label may vary, but it should not look like a normal local Windows-only window.
Open the Integrated Terminal
Open the Terminal menu and create a new terminal.
Run:
pwd
The path should begin with something similar to:
/home/
It should not display a Windows-style path beginning with:
C:\
Next, run:
uname -a
The result should contain Linux environment information.
You can also run:
whoami
This should display the Linux username you created during WSL setup.
Together, these commands confirm that:
- the terminal is running inside Linux;
- the current directory is inside the WSL file system;
- the terminal is using your Linux account.
Confirm the Shell
Run:
echo $SHELL
The result may resemble:
/bin/bash
or another Linux shell path.
This confirms that the integrated terminal is not using Windows PowerShell.
Create and Edit a Test File
In the VS Code Explorer, create a file named:
README.md
Add the following content:
# WSL and VS Code Practice
This project is stored inside my WSL Linux environment.
## Environment Check
- Editor: Visual Studio Code
- Operating environment: WSL
- Project location: Linux home directory
Save the file.
Return to the integrated terminal and run:
ls
You should see:
README.md
Now display the file contents:
cat README.md
The text you added in VS Code should appear in the terminal.
This confirms that the editor and the WSL terminal are working with the same project files.
Understand Windows Paths and WSL Paths
A major source of confusion is that Windows and WSL can both access some of the same files, but they describe locations differently.
A Windows path may look like:
C:\Users\Alex\Documents\project
Inside WSL, the same Windows folder may appear as:
/mnt/c/Users/Alex/Documents/project
A project stored inside the Linux home directory may look like:
/home/alex/projects/project
These locations are not interchangeable.
Windows File System
Files under paths such as:
C:\Users\Alex
belong to the Windows file system.
Inside WSL, Windows drives are commonly mounted under:
/mnt/
For example:
/mnt/c/
represents the Windows C drive.
Linux File System
Files under paths such as:
/home/alex
belong to the WSL Linux file system.
For Linux-based development tools, this is often the better place to store active projects.
Why Project Location Matters
Development tools may behave differently depending on where the project is stored.
Possible issues include:
- slower file operations;
- file-watching delays;
- permission differences;
- inconsistent line endings;
- path-format problems;
- package-manager errors;
- tools running from different environments;
- duplicate dependency folders.
For a WSL-centered workflow, keep Linux-based projects under a location such as:
~/projects
Then open them through a WSL-connected VS Code window.
This reduces the chance that Windows tools and Linux tools will modify the same project in inconsistent ways.
Do Not Mix Terminals Without Realizing It
VS Code can open different terminal profiles.
Depending on your configuration, the terminal menu may offer:
- PowerShell;
- Command Prompt;
- Git Bash;
- Ubuntu or another WSL distribution;
- a Linux shell inside a WSL-connected window.
The terminal name alone is not always enough to confirm the environment.
Use the path and commands as evidence.
Inside Linux:
pwd
should show a path beginning with /.
Inside PowerShell:
Get-Location
may show a path beginning with a Windows drive letter.
Before installing packages or running project commands, confirm:
- the active terminal;
- the current directory;
- the file system where the project is stored.
This three-part check prevents many beginner errors.
Install Extensions in the Correct Environment
When VS Code is connected to WSL, the Extensions view may distinguish between extensions installed on Windows and extensions installed inside WSL.
Some extensions affect only the editor interface and can run locally on Windows.
Other extensions need access to:
- the Linux project files;
- the Linux runtime;
- language servers;
- command-line tools;
- the terminal environment.
These may need to be installed inside WSL.
VS Code normally indicates where an extension is installed or where it needs to run.
When installing an extension, pay attention to labels such as:
- installed locally;
- install in WSL;
- enabled in this workspace;
- disabled in this environment.
Do not assume that installing an extension once makes it available in every environment.
Later, when we install GitHub Copilot and configure Claude Code, we will check whether each component belongs on the Windows side, the WSL side, or both.
Reopen a WSL Project Later
After closing VS Code, you can reopen the project in several ways.
Open from the WSL Terminal
Run:
cd ~/projects/wsl-vscode-practice
code .
This method is explicit and reliable.
Use the VS Code Recent List
Open VS Code and check the recent folders or workspaces.
A recent WSL project may appear with an environment label.
Confirm that the reopened window is still connected to WSL before running commands.
Connect First, Then Open the Folder
Connect to WSL from the Command Palette.
Then use the File menu to open:
/home/your-username/projects/wsl-vscode-practice
Make sure you are browsing the Linux file system rather than selecting a similarly named Windows folder.
Common VS Code and WSL Problems
VS Code Opens the Folder as a Windows Project
Check the terminal.
If the path begins with C:\, the folder may be open in a normal Windows window.
Close the folder, connect to WSL, and reopen the Linux path.
A Linux-based project should normally appear under a path beginning with:
/home/
The Terminal Opens PowerShell Instead of Linux
Confirm that the VS Code window itself is connected to WSL.
If it is not, connect through the Command Palette or reopen the project with:
code .
If the window is connected but a manually selected terminal profile opens PowerShell, create a new terminal and choose the Linux shell associated with the WSL environment.
The Explorer Shows a Different Folder Than the Terminal
The terminal may have been moved to another directory with cd.
Run:
pwd
Compare the result with the folder displayed at the top of the Explorer.
For beginner workflows, keep the terminal inside the project root unless a command specifically requires another directory.
An Extension Works on Windows but Not in WSL
Open the Extensions view and check where the extension is installed.
It may need a separate installation inside the WSL environment.
Also verify whether the extension depends on a Linux-side runtime or executable.
Files Are Stored Under /mnt/c/
This is not automatically wrong. WSL can work with files stored on Windows drives.
However, Linux-heavy development tools may perform more consistently when projects are stored under:
/home/your-username/
For this series, use:
~/projects
unless a later tutorial gives a specific reason to use a Windows path.
VS Code Takes a Long Time on the First Connection
The first WSL connection may require VS Code to install support components inside the Linux environment.
Allow the process to complete and read any visible error messages.
Later connections are normally faster.
WSL Stops Responding
Save your work and close active development processes.
From Windows PowerShell, you can stop WSL with:
wsl --shutdown
Then reopen the distribution.
Do not run this command while a database, file operation, package installation, or development server is performing important work.
A Practical Folder Strategy
A simple project structure reduces mistakes.
Inside WSL, use:
/home/your-username/projects
Place each project in its own folder:
/home/your-username/projects/
├── wsl-vscode-practice/
├── first-web-app/
└── ai-coding-experiments/
Avoid placing unrelated files directly in the projects folder.
Each project should have its own:
- source files;
- documentation;
- configuration;
- dependency files;
- Git repository;
- environment settings.
When starting work, move into the correct folder and open it:
cd ~/projects/first-web-app
code .
This creates a clear connection between the terminal location and the VS Code workspace.
In professional development, consistency like this is more valuable than a complicated folder system. A predictable location helps humans, scripts, editors, and AI tools understand the same project context.
Why This Matters for AI-Assisted Development
AI coding tools depend heavily on context.
If the wrong folder is open, an AI assistant may:
- fail to find expected files;
- inspect an incomplete project;
- create files in the wrong directory;
- use the wrong package manager;
- run commands in the wrong environment;
- modify a duplicate copy of the project.
Before asking an AI tool to make changes, confirm:
pwd
Then inspect the top-level files:
ls
These two commands provide a quick environment check.
You should know:
- where the project is stored;
- which operating environment is active;
- which files belong to the project;
- whether the terminal is in the project root.
A strong prompt cannot compensate for a confused workspace.
Verify Your VS Code and WSL Setup
Before continuing to the next article, confirm that you can complete each of these actions:
- Open WSL.
- Move into
~/projects. - Create a project folder.
- Open the folder with
code .. - See a WSL connection indicator in VS Code.
- Open the integrated terminal.
- Run
pwd and see a Linux path. - Run
uname -a and see Linux information. - Create a file in the VS Code Explorer.
- Read the same file with the Linux terminal.
- Identify the difference between
/home/ and /mnt/c/. - Reopen the project after closing VS Code.
A final verification sequence is:
cd ~/projects/wsl-vscode-practice
pwd
ls
code .
Inside the VS Code terminal, run:
pwd
whoami
uname -a
The results should confirm that the project and terminal are both operating inside WSL.
Conclusion
Visual Studio Code and WSL work well together because they separate the user interface from the development environment.
VS Code gives you a familiar editor, file explorer, terminal panel, and extension system. WSL provides the Linux file system, shell, and command-line environment used by many modern development tools.
The most important practice is consistency. Store WSL-based projects in a clear Linux location, open them through a WSL-connected VS Code window, and verify the terminal before running commands.
You now have a development workspace where Windows, VS Code, and Linux can work together without mixing their roles.
The next article will move from the local development environment to GitHub. We will create a GitHub account, review essential security and profile settings, and prepare for storing project repositories online.
Frequently Asked Questions
Do I have to store every project inside WSL?
No.
Projects designed for Windows-specific tools may be better stored in the Windows file system. Projects using Linux-oriented tools often work more consistently inside the WSL file system.
The important point is to choose deliberately and avoid switching between environments without understanding the consequences.
Can I open WSL files from Windows File Explorer?
Yes. Windows provides ways to browse WSL files.
However, avoid editing or moving Linux system files with tools that do not understand Linux permissions and metadata. For project work, using a WSL-connected VS Code window is generally safer and more consistent.
Why does VS Code ask me to install the same extension again?
An extension may be installed on the Windows side but not inside the WSL environment.
Extensions that need access to Linux tools or project files may require a separate WSL installation. Check the extension details and the environment labels shown by VS Code.
Comments
Post a Comment