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

•
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?
- •Convert Windows paths properly
- •Use Linux-native paths