Skip to content

WSL (Windows Subsystem for Linux)

A real Linux kernel running inside Windows. WSL2 gives you Ubuntu (or any distro), bash, Docker, and GPU-accelerated deep learning — without a VM or dual boot.

Table of Contents

Installation / Setup

# In an ADMIN PowerShell (WSL2 default):
wsl --install
# installs the virtual-machine platform + Ubuntu; reboot when asked

# Prefer a specific distro / version:
wsl --install -d Ubuntu-24.04
wsl --set-default-version 2

wsl                # enter the default distro (bash prompt)
wsl -d Ubuntu      # pick a distro
exit               # leave WSL back to Windows
Command (Windows side) Meaning
wsl -l -v list distros + WSL version
wsl --set-default -d Ubuntu default distro
wsl --shutdown stop all WSL (frees RAM)
wsl --terminate Ubuntu stop one distro
wsl --update update WSL kernel
wsl --export / --import move/backup a distro

Core Syntax

The filesystem bridge

Location Contents
/home/<user>/ your Linux home (keep work here!)
/mnt/c/Users/you/... your Windows files from Linux
\\wsl$\Ubuntu\home\<user> your Linux files from Windows (Explorer)
\\wsl.localhost\Ubuntu\... newer UNC path 
# From bash, reach Windows files:
cd /mnt/c/Users/ada/projects
# From Windows Explorer, reach Linux files:
#   \\wsl$\Ubuntu\home\ada\   (or: wsl --cd ~ ; explorer.exe .)

Rule of thumb: keep project files on the Linux filesystem (~/...) — reads/writes to /mnt/c are slower (cross-filesystem). Large shared datasets may live on Windows; copy to Linux for heavy I/O.

Running Windows tools from Linux & vice versa

# From bash -> Windows:
notepad.exe file.txt        # open in Windows Notepad
explorer.exe .              # open current folder in Explorer
code .                      # launch VS Code (WSL extension handles it)
/mnt/c/Windows/System32/ipconfig.exe   # run any Windows exe

# From PowerShell/CMD -> Linux:
wsl ls -la
wsl python3 train.py        # run Linux python directly

Networking note

WSL2 shares the Windows network via NAT — localhost works both ways for most dev servers (a Jupyter server in WSL is reachable at http://localhost:8888 from Windows browsers).

Common Operations

Python & data science inside WSL

sudo apt update && sudo apt install -y python3 python3-venv python3-pip
python3 -m venv .venv && source .venv/bin/activate
pip install numpy pandas jupyter        # see python-virtual-environments.md
jupyter lab --no-browser --port=8888    # open http://localhost:8888 on Windows

GPU support (CUDA in WSL2)

# 1. Install Windows NVIDIA driver (WSL-capable, from nvidia.com)
# 2. Inside Ubuntu, install CUDA toolkit via NVIDIA's WSL instructions
nvidia-smi                 # should show the GPU inside WSL
python -c "import torch; print(torch.cuda.is_available())"   # True

Docker inside WSL (instead of Docker Desktop)

# Docker Desktop with WSL2 backend is the easiest path (Windows install)
# then from Windows Terminal: docker ps   (works against WSL engine)
# Pure WSL alternative: install docker.io + systemctl-in-wsl or start dockerd

VS Code integration

# 1. Install the "WSL" VS Code extension
# 2. From WSL:  code .
# VS Code reopens as a Remote-WSL window using the Linux toolchain + venv

Practical Examples

1. Full data-science environment in one session

cd ~ && mkdir -p project && cd project
python3 -m venv .venv && source .venv/bin/activate
pip install -U pip && pip install pandas scikit-learn torch jupyterlab
jupyter lab --ip=0.0.0.0 --no-browser &
# Windows browser -> http://localhost:8888

2. Bridge a Windows dataset without copying

ln -s /mnt/d/datasets/imagenet ~/datasets/imagenet   # symlink, no copy
# but for training loops, copy to Linux first for speed:
cp -r /mnt/d/datasets/train ~/data/

3. Run the same script on Windows and Linux

# Windows side (PowerShell):
wsl python3 train.py --epochs 10
python train.py --epochs 10        # if python installed on Windows too

Common Patterns

# Quick one-shot commands from Windows
wsl -e bash -lc "df -h"
wsl -e python3 -c "import pandas; print(pandas.__version__)"

# Stop WSL to reclaim RAM when idle
wsl --shutdown

Best Practices

  • Work in ~ (Linux FS), not /mnt/c, for performance and correct permissions.
  • Use the WSL VS Code extension so debugging/linting use the Linux interpreter.
  • Activate your Linux venv — don't confuse it with a Windows Python install.
  • GPU: keep the NVIDIA driver updated on Windows; CUDA lives inside WSL.
  • Back up config: dotfiles in ~; Windows files stay on /mnt/c automatically.
  • Prefer wsl.exe calls from scripts to keep Windows & Linux toolchains composable.
  • Keep it minimal: one or two distros; wsl --shutdown when memory runs short.

Common Mistakes

Mistake Consequence Fix
Editing Linux files with Windows tools that write CRLF Broken bash scripts / odd diffs Use VS Code WSL (LF-aware) or sed -i 's/\r$//'
Storing big repos under /mnt/c Slow I/O, file-lock issues ~/ on ext4
Installing python on Windows but running wsl python Confused environments Check which python inside WSL
Forgetting wsl --shutdown WSL holds RAM after use Shut down when done
Mixing \\wsl$ path styles Explorer "path not found" Use \\wsl.localhost\Ubuntu\... on newer builds
Expecting systemd by default (older WSL) systemctl fails Use wsl.conf [boot] systemd=true (WSL 0.67+)
GPU not visible Driver without WSL support Install current NVIDIA driver from nvidia.com

Troubleshooting

Symptom Cause Fix
WSL is not installed Feature missing wsl --install as admin; reboot
The requested operation is not supported (old) WSL1 legacy wsl --set-version Ubuntu 2
Virtualization errors BIOS/Hyper-V off Enable virtualization in firmware; Hyper-V platform on
wsl: command not found in bash Running inside WSL already It's a Windows exe — call from PowerShell/CMD
OOM inside WSL RAM limit .wslconfig: memory=8GB, processors=4
network slow to /mnt/c Cross-FS I/O Copy to ~; or .wslconfig networking tweaks
code . opens empty window WSL extension missing Install "WSL" extension; retry from inside WSL

Official Documentation

Last Updated

2026-09-06 — Initial version.