|$ curl https://forge-ai.dev/api/markdown?path=docs/linux/wsl
$cat docs/wsl.md
updated Recently·18 min read·published
WSL
Introduction
WSL (Windows Subsystem for Linux) lets you run a Linux environment directly on Windows without a traditional virtual machine. It is the best way for Windows users to learn Linux and run Linux-native developer tools.
Installation
wsl-install.ps1
POWERSHELL
| 1 | # Install WSL with default Ubuntu distribution |
| 2 | wsl --install |
| 3 | |
| 4 | # Restart is required. Then install a specific distribution |
| 5 | wsl --install -d Debian |
| 6 | wsl --install -d Fedora |
| 7 | |
| 8 | # List available distributions |
| 9 | wsl --list --online |
| 10 | |
| 11 | # Set default version to WSL 2 |
| 12 | wsl --set-default-version 2 |
ℹ
info
WSL 2 uses a real Linux kernel inside a lightweight VM and provides better compatibility and performance than WSL 1.
Basic Commands
wsl-commands.ps1
POWERSHELL
| 1 | # Launch default distribution |
| 2 | wsl |
| 3 | |
| 4 | # Run a command without entering WSL |
| 5 | wsl ls -la |
| 6 | wsl python3 --version |
| 7 | |
| 8 | # Launch a specific distribution |
| 9 | wsl -d Ubuntu |
| 10 | |
| 11 | # Shut down WSL |
| 12 | wsl --shutdown |
| 13 | |
| 14 | # Terminate a specific distribution |
| 15 | wsl -t Ubuntu |
| 16 | |
| 17 | # List running distributions |
| 18 | wsl --list --verbose |
File Sharing
WSL can access Windows files and Windows can access WSL files, but performance is best when project files live inside the Linux filesystem.
file-sharing.sh
Bash
| 1 | # Inside WSL, Windows drives are mounted |
| 2 | ls /mnt/c/Users/Alice/Documents |
| 3 | |
| 4 | # Access WSL files from Windows Explorer |
| 5 | # Run inside WSL: |
| 6 | explorer.exe . |
| 7 | |
| 8 | # Access via network path from Windows |
| 9 | # \wsl$Ubuntuhomealiceprojects |
⚠
warning
Avoid storing project files on /mnt/c and running Linux tools against them. File system performance is much slower across the boundary.
Windows Integration
integration.sh
Bash
| 1 | # Open current directory in VS Code |
| 2 | code . |
| 3 | |
| 4 | # Open a file in the default Windows browser |
| 5 | xdg-open https://forgelearn.dev |
| 6 | |
| 7 | # Use Windows Git credentials inside WSL |
| 8 | git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe" |
| 9 | |
| 10 | # Interop: run Windows executables from WSL |
| 11 | notepad.exe file.txt |
| 12 | cmd.exe /c dir |
Optimization
.wslconfig
TEXT
| 1 | # ~/.wslconfig on Windows side |
| 2 | [wsl2] |
| 3 | memory=8GB |
| 4 | processors=4 |
| 5 | swap=2GB |
| 6 | localhostForwarding=true |
✓
best practice
Limit WSL memory in .wslconfig to prevent the Vmmem process from consuming all host RAM, especially when running Docker Desktop or large Node.js builds.
Community
Get help on Slack, Discord or VIP
Stuck on a guide? Join the community and ask.