Environnement de développement Wsl2
/SKILLPièges courants et solutions pour le développement en WSL2.
WSL2 Development Environment
Common pitfalls and solutions for developing in WSL2.
When to Use
- Debugging WSL2-specific issues
- Setting up development environment in WSL2
- Troubleshooting network, filesystem, or GUI issues
- Running Tauri/GUI applications in WSL2
Network Issues
Cannot Connect to Localhost from Windows
Symptom: Windows browser can't reach WSL2 server
Solution: Use the WSL2 IP address or enable mirrored networking:
# Get WSL2 IP
hostname -I | awk '{print $1}'
# Or enable mirrored networking (Windows 11 22H2+)
# In %USERPROFILE%\.wslconfig:
[wsl2]
networkingMode=mirrored
Port Forwarding Not Working
Symptom: External devices can't reach WSL2 services
Solution: Forward ports from Windows:
# PowerShell as Admin
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=$(wsl hostname -I)
DNS Resolution Failures
Symptom: `ping: unknown host` or slow DNS
Solution: Configure DNS manually:
# /etc/wsl.conf
[network]
generateResolvConf = false
# Then create /etc/resolv.conf
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
sudo chattr +i /etc/resolv.conf # Prevent overwrite
Filesystem Issues
Slow File Operations in /mnt/c
Symptom: npm install, cargo build extremely slow
Root Cause: Cross-filesystem operations are slow in WSL2.
Solution: Keep projects in Linux filesystem:
# Good - fast
~/projects/myapp
# Bad - slow
/mnt/c/Users/name/projects/myapp
File Permission Issues
Symptom: Can't execute scripts, wrong permissions
Solution: Configure metadata in wsl.conf:
# /etc/wsl.conf
[automount]
enabled = true
options = "metadata,umask=22,fmask=11"
File Watching Not Working
Symptom: Hot reload doesn't detect changes
Root Cause: inotify doesn't work across filesystems.
Solution: Use polling or keep files in Linux:
# For Next.js
WATCHPACK_POLLING=true bun dev
# For Vite
export CHOKIDAR_USEPOLLING=true
# Best: move project to Linux filesystem
GUI/Display Issues
GUI Apps Don't Start
Symptom: `cannot open display` error
Solution: Use WSLg (Windows 11) or configure X server:
# Check if WSLg is working
echo $DISPLAY # Should be :0 or similar
# Test with simple app
sudo apt install x11-apps
xeyes
Tauri/GTK Apps Crash
Symptom: gdk-pixbuf or GTK errors on startup
Solution: Set environment variables:
# Add to ~/.bashrc
if grep -qi microsoft /proc/version; then
export GDK_BACKEND=x11
export WEBKIT_DISABLE_COMPOSITING_MODE=1
export LIBGL_ALWAYS_SOFTWARE=1
fi
Fonts Look Bad
Symptom: Jagged or missing fonts in GUI apps
Solution: Install Windows fonts in WSL:
sudo apt install fontconfig
sudo ln -s /mnt/c/Windows/Fonts /usr/share/fonts/windows
fc-cache -fv
Memory/Performance
WSL2 Using Too Much Memory
Symptom: Windows slows down, WSL2 consuming all RAM
Solution: Limit memory in .wslconfig:
# %USERPROFILE%\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB
High CPU from Vmmem
Symptom: Vmmem process using CPU when WSL idle
Solution: Configure memory reclaim:
# %USERPROFILE%\.wslconfig
[wsl2]
memory=8GB
[experimental]
autoMemoryReclaim=gradual
Development Setup
Recommended .bashrc Additions
# WSL2-specific setup
if grep -qi microsoft /proc/version; then
# GUI support
export GDK_BACKEND=x11
export WEBKIT_DISABLE_COMPOSITING_MODE=1
# Docker in WSL2
export DOCKER_HOST=unix:///var/run/docker.sock
# Alias to open files in Windows
alias open='explorer.exe'
alias code='code.exe'
# Fix for slow git in mounted drives
alias wingit='/mnt/c/Program\ Files/Git/bin/git.exe'
fi
Recommended /etc/wsl.conf
[boot]
systemd=true
[automount]
enabled = true
options = "metadata,umask=22,fmask=11"
[interop]
enabled = true
appendWindowsPath = true
Common Commands
# Restart WSL (from Windows PowerShell)
wsl --shutdown
# Check WSL version
wsl -l -v
# Set default distro
wsl --set-default Ubuntu
# Export/backup WSL
wsl --export Ubuntu ubuntu-backup.tar
# Check if running in WSL2
uname -r # Should contain "microsoft"
Troubleshooting Checklist
- Is it a filesystem issue?
- Move project to Linux filesystem
- Check file permissions
- Is it a network issue?
- Check Windows Firewall
- Verify WSL2 IP reachable
- Is it a GUI issue?
- Verify DISPLAY is set
- Try WSLg or X server
- Is it a memory issue?
- Configure .wslconfig limits
- Restart WSL
- Is it a path issue?
