Developing with WSL and VS Code: Resolving `code: command not found` and Optimizing Performance

Sat, 31 Oct 2026 05:18:00 +0800

Pairing WSL (Windows Subsystem for Linux) with VS Code has become one of the most popular development workflows for full-stack and indie developers on Windows. However, during configuration, it is common to run into shell errors or performance bottlenecks caused by cross-filesystem file handling. This post documents the journey from encountering the issue to diagnosing the root cause and implementing the final solution.

1. Encountering the Issue

After switching the default WSL shell to an efficient zsh environment, attempting to launch the editor directly from the project directory via the command line resulted in a roadblock:

➜ zhangdapeng.dev git:(main) code .
zsh: command not found: code

This is a classic issue: The terminal inside WSL (especially after configuring zsh) fails to recognize the Windows-side VS Code executable.

2. Root Cause & Deep Dive

There are two primary reasons why this error occurs:

WSL Configuration Disables Interoperability: In /etc/wsl.conf, if appendWindowsPath is set to false, WSL prevents Windows environment variables (PATH) from being appended to Linux. This isolates the Linux environment and stops it from invoking Windows .exe applications.
zsh Path Inheritance Miss: When migrating from the default bash to zsh, certain cross-system environment variables might not refresh or inherit correctly inside the new shell profile.

The “Slow” vs “Fast” Debate: Where to Store Your Code?

While fixing the connection issue, developers often face a choice of directory location (/mnt vs ~), which fundamentally shapes the speed of the development experience:

The Slow Path (Code on Windows side: /mnt/c/...): Storing code on a Windows partition and accessing it through WSL incurs heavy I/O performance degradation. Because data must constantly cross two entirely different file systems (NTFS and ext4), operations like git status, npm install, or project compilation feel visibly sluggish.
The Fast Path (Code inside WSL side: ~/...): Storing projects natively within the Linux file system ensures near-native performance. The Remote-WSL extension deploys a highly optimized, lightweight background server inside Linux, unlocking maximum compilation speeds.

Is there anything wrong with staying on the “slow” path?

Not necessarily! Launching VS Code from a /mnt/ directory might introduce a slight lag during heavy file tasks, but if the execution speed is acceptable to you, it is perfectly fine. The biggest advantage? Security and simplicity. Even if your WSL instance gets corrupted, your source code remains safe on your host Windows drive, allowing easy backups and management using standard Windows GUI tools.

3. The Solutions

Step 1: Verify and Enable Windows Path Appending

First, ensure that WSL is permitted to inherit environment paths from Windows.

Open the WSL configuration file:
```
sudo nano /etc/wsl.conf
```
Check the [interop] section and ensure appendWindowsPath is not set to false (change it to true or remove the line entirely):
```
[interop]
appendWindowsPath = true
```
If changes were made, open Windows PowerShell and run wsl --shutdown to restart the subsystem.

Step 2: Manually Inject the VS Code Path into `.zshrc`

If interoperability is enabled but the command still fails, the most foolproof method is manually appending the entry to your zsh configuration:

Open your shell configuration file:
```
nano ~/.zshrc
```

Scroll to the absolute bottom of the file and paste the following line (make sure to replace YourWindowsUsername with your actual Windows account folder name):

# Manually inject the Windows VS Code binary path into zsh
export PATH=\$PATH:"/mnt/c/Users/YourWindowsUsername/AppData/Local/Programs/Microsoft VS Code/bin"

Save, exit (Ctrl + O, Enter, Ctrl + X), and refresh your terminal:
```
source ~/.zshrc
```

Step 3: The Alternative Workspace Workaround

If permission restrictions or security policies prevent the terminal workflow from functioning, you can bypass the command line entirely:

Launch VS Code natively from your Windows desktop.
Press Ctrl + Shift + P to open the Command Palette, type WSL, and select WSL: Connect to WSL.
Once connected, use the top menu to navigate to File -> Open Folder. You can seamlessly browse and open folders located anywhere inside the WSL instance or your /mnt drives.

4. Summary & Best Practices

Leveraging WSL alongside VS Code’s remote architectures provides an incredibly powerful sandbox environment on Windows.

For Ultimate Speed: Migrate your code repositories directly to the Linux home directory (~) using cp -r.
For Ease of Mind and Visibility: Keep your folders on the Windows side (/mnt/), map your PATH variable correctly, and enjoy an interconnected development stack.

VSCode on Daniel Zhang