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: ``bash # 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 # 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: `bash # /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: `bash # 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: `bash # /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: `bash # 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: `bash # 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: `bash # 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: `bash 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: `ini # %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: `ini # %USERPROFILE%\.wslconfig [wsl2] memory=8GB [experimental] autoMemoryReclaim=gradual ` ## Development Setup ### Recommended .bashrc Additions `bash # 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 `ini [boot] systemd=true [automount] enabled = true options = "metadata,umask=22,fmask=11" [interop] enabled = true appendWindowsPath = true ` ## Common Commands `bash # 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 1. Is it a filesystem issue? - Move project to Linux filesystem - Check file permissions 2. Is it a network issue? - Check Windows Firewall - Verify WSL2 IP reachable 3. Is it a GUI issue? - Verify DISPLAY is set - Try WSLg or X server 4. Is it a memory issue? - Configure .wslconfig limits - Restart WSL 5. Is it a path issue?