Installation, C/C++ development setup, VS Code integration, and troubleshooting manual

Applies to supported Windows 10 and Windows 11 systems. Run commands in the shell indicated by each section. This guide uses the distribution name Ubuntu-22.04 and example Linux username faraz.

Windows Subsystem for Linux (WSL 2) runs Ubuntu alongside Windows without dual booting. You can use Bash, GCC/G++, CMake, Git, GDB, Python, and VS Code connected to Linux.

Before starting: Save your work. Installation or configuration changes may require restarting Windows or shutting down WSL. Windows virtualization support must be enabled; if installation reports virtualization errors, check firmware virtualization and Windows features.

Open Windows PowerShell or Windows Terminal as Administrator.

Check the current installation:

wsl --status
wsl --list --verbose

If WSL is not installed, install its platform components without a distribution:

wsl --install --no-distribution

Restart Windows if requested. Then set WSL 2 as the default and install the specific Ubuntu release:

wsl --set-default-version 2
wsl --install -d Ubuntu-22.04

If the distribution download stalls, try the web-download option:

wsl --install --web-download -d Ubuntu-22.04

Do not run the installation command again if Ubuntu 22.04 is already installed. Instead, launch the existing distribution:

wsl -d Ubuntu-22.04

When prompted, create a Linux username and password, for example:

Enter new UNIX username: faraz
New password:
Retype new password:

The password does not display while you type. Your Linux password is separate from your Windows password.

In PowerShell:

wsl --list --verbose

Example output (the state may be Running or Stopped):

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

If Ubuntu shows version 1, convert it from PowerShell:

wsl --set-version Ubuntu-22.04 2

In the Ubuntu terminal:

lsb_release -a

Check that the release is Ubuntu 22.04. You can also run:

cat /etc/os-release
uname -r

Run the following commands inside Ubuntu:

sudo apt update
sudo apt upgrade -y

Install commonly used C/C++ and embedded-development utilities:

sudo apt install -y \
    build-essential \
    cmake \
    ninja-build \
    git \
    gdb \
    python3 \
    python3-pip \
    pkg-config

Verify the tools:

gcc --version
g++ --version
cmake --version
git --version
python3 --version

For a quick compiler test:

mkdir -p ~/projects
cd ~/projects
printf '#include <iostream>\nint main() { std::cout << "Hello from Ubuntu!\\n"; }\n' > hello.cpp
g++ -std=c++17 -Wall -Wextra hello.cpp -o hello
./hello

Expected output:

Hello from Ubuntu!

1. Install Visual Studio Code for Windows from https://code.visualstudio.com/.
2. Open VS Code on Windows and install Microsoft's WSL extension (ms-vscode-remote.remote-wsl): https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl.
3. In the Ubuntu terminal, run:

mkdir -p ~/projects
cd ~/projects
code .

VS Code should open a window connected to WSL. The bottom-left remote indicator should identify the WSL environment. On first connection, VS Code may install its server components inside Ubuntu.

Performance tip: Keep Linux source trees in the Linux filesystem (for example, ~/projects) rather than /mnt/c/... or /mnt/d/... when compiling with Linux tools. You can browse the Linux files from Windows via \\wsl$\Ubuntu-22.04\home\faraz\projects (adjust the username).

Running code . inside Ubuntu produces an error similar to:

/mnt/d/Microsoft VS Code/bin/code: 62: /mnt/d/Microsoft VS Code/Code.exe: Exec format error

This means Linux attempted to launch a Windows executable but the launch failed. One possible cause is broken or disabled WSL Windows interoperability; the error alone does not prove that this is the cause. Check interoperability before reinstalling VS Code.

In Ubuntu, run:

cmd.exe /c echo hello
/mnt/c/Windows/System32/cmd.exe /c echo hello

Expected result for each command:

hello

• Both work: Windows interoperability is functioning; focus on the VS Code path or installation.
• Both report Exec format error: Investigate WSL interoperability and its executable handler.
• Only the full path works: Investigate the Linux PATH and Windows-path propagation.
• command not found or another error: Record the exact output; it is a different symptom.

In Ubuntu:

cat /etc/wsl.conf

For example, an existing file might contain:

[boot]
systemd=true

[user]
default=faraz

This file is not inherently wrong. Omission of [interop] does not itself mean interoperability is disabled; WSL normally enables it by default. If the executable test fails, you can explicitly enable it as a troubleshooting step.

In Ubuntu:

sudo nano /etc/wsl.conf

Preserve existing sections and add the interoperability settings:

[boot]
systemd=true

[user]
default=faraz

[interop]
enabled=true
appendWindowsPath=true

Replace faraz with your actual Linux username if different. enabled=true allows launching Windows processes; appendWindowsPath=true adds Windows PATH entries to the Linux PATH.

In nano, save with Ctrl+O, Enter, and exit with Ctrl+X.

Restart WSL from Windows PowerShell (this stops all running WSL distributions and processes):

wsl --shutdown
wsl -d Ubuntu-22.04

Back in Ubuntu, retest:

cmd.exe /c echo hello
cd ~/projects
code .

Run in Ubuntu and copy the complete output, including errors:

cmd.exe /c echo hello
cat /etc/wsl.conf
ls -l /proc/sys/fs/binfmt_misc/
cat /proc/sys/fs/binfmt_misc/WSLInterop
command -v code
which code

WSLInterop may be absent or the handler may be registered under a different name; a missing file is diagnostic evidence, not a reason to create it manually. If /proc/sys/fs/binfmt_misc/ is empty or missing expected entries, investigate the WSL executable handler and systemd/binfmt configuration rather than changing random files.

If cmd.exe works but code . still fails, inspect the VS Code launcher and Windows executable path:

command -v code
ls -l '/mnt/d/Microsoft VS Code/Code.exe'

Confirm VS Code launches normally from Windows and that the Microsoft WSL extension is installed. If Windows VS Code itself does not launch, repair or reinstall the Windows application using its official installer. Do not install the Linux desktop edition of VS Code merely to fix Windows interoperability.

If Windows interoperability still fails, collect WSL status and version information in PowerShell:

wsl --status
wsl --version
wsl --list --verbose

If wsl --version is not recognized, the installed WSL package may be older. Review Microsoft's current WSL guidance before changing Windows features or updating WSL. You can also try:

wsl --update
wsl --shutdown

Restart Ubuntu and repeat the cmd.exe test. Avoid disabling systemd or changing binfmt registrations without confirming the actual cause.

• Microsoft WSL installation: https://learn.microsoft.com/en-us/windows/wsl/install
• Microsoft WSL configuration (wsl.conf): https://learn.microsoft.com/en-us/windows/wsl/wsl-config
• Microsoft WSL troubleshooting: https://learn.microsoft.com/en-us/windows/wsl/troubleshooting
• VS Code with WSL: https://code.visualstudio.com/docs/remote/wsl
• Microsoft VS Code WSL extension: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl

Troubleshooting principle: Test cmd.exe first, change only the configuration implicated by the test, restart WSL, and retest before modifying anything else.