WSL

Windows Subsystem for Linux Reference

wsl linux windows development

---

Install WSL

# Install WSL with Ubuntu (default)
wsl --install
 
# Install specific distro
wsl --install -d Ubuntu-22.04
 
# List available distros
wsl --list --online

Update WSL

wsl.exe --update

---

WSL Configuration

/etc/wsl.conf (per-distro)

Located inside each WSL distro. Create/edit the file:

sudo nano /etc/wsl.conf

Common settings:

[boot]
systemd=true                    # Enable systemd (WSL2 only)
 
[network]
generateResolvConf = false      # Don't auto-generate resolv.conf
hostname = dev-machine          # Custom hostname
 
[interop]
enabled = true                  # Allow running Windows apps
appendWindowsPath = true        # Include Windows PATH
 
[automount]
enabled = true                  # Mount Windows drives
root = /mnt/                    # Mount point
options = "metadata,umask=22,fmask=11"
 
[user]
default = myuser                # Default user on startup

Note: Changes require wsl --shutdown then restart.

.wslconfig (global, Windows-side)

Located at %UserProfile%\.wslconfig:

[wsl2]
memory=8GB                      # Limit memory
processors=4                    # Limit CPUs
swap=4GB                        # Swap size
localhostForwarding=true        # Access WSL from localhost
 
[experimental]
networkingMode=mirrored         # Mirror Windows networking
dnsTunneling=true
autoProxy=true

---

Custom resolv.conf

If you need specific DNS servers:

1. Edit /etc/wsl.conf:

[network]
generateResolvConf = false

2. Delete and recreate resolv.conf:

sudo rm /etc/resolv.conf
sudo nano /etc/resolv.conf

3. Add your nameservers:

nameserver 10.155.204.179
nameserver 10.235.136.98
nameserver 8.8.8.8

4. Make it immutable (optional, prevents overwrite):

sudo chattr +i /etc/resolv.conf

5. Restart WSL:

wsl --shutdown

---

WSL Commands (Windows side)

Command	Description
wsl	Start default distro
wsl -d Ubuntu	Start specific distro
wsl --list --verbose	List installed distros with status
wsl --shutdown	Shut down all distros
wsl --terminate Ubuntu	Terminate specific distro
wsl --status	Show WSL status and version
wsl --set-default Ubuntu	Set default distro
wsl --set-version Ubuntu 2	Convert distro to WSL2
wsl --export Ubuntu backup.tar	Export distro to file
wsl --import MyDistro C:\WSL backup.tar	Import distro from file
wsl --unregister Ubuntu	Remove distro (deletes data!)

Run Commands Directly

# Run single command
wsl ls -la /home
 
# Run as specific user
wsl -u root whoami
 
# Run in specific distro
wsl -d Ubuntu-22.04 cat /etc/os-release

---

File Access

Access Windows Files from WSL

# Windows drives mounted at /mnt/
cd /mnt/c/Users/username/Documents
 
# Faster access to Windows files
cd /mnt/c/Projects

Access WSL Files from Windows

\\wsl$\Ubuntu\home\username

Or in File Explorer: \\wsl$

Tip: For best performance, keep project files in the Linux filesystem (/home/user/) rather than on /mnt/c/.

---

Networking

Mirror Mode (Windows 11 22H2+)

In .wslconfig:

[experimental]
networkingMode=mirrored

Benefits:

• WSL shares Windows IP address
• No port forwarding needed
• VPN works automatically
• IPv6 support

Check IP Address

# WSL IP (NAT mode)
hostname -I
 
# Windows host IP
cat /etc/resolv.conf | grep nameserver

Port Forwarding (NAT mode)

Windows automatically forwards localhost ports. To access from other machines:

# Forward port 3000 to WSL
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=$(wsl hostname -I)

---

Common Tasks

Open Current Directory in Windows Explorer

explorer.exe .

Open File with Default Windows App

wslview file.pdf
# or
explorer.exe file.pdf

Copy/Paste

• Copy from WSL terminal: Select text (auto-copies in Windows Terminal)
• Paste to WSL: Right-click or Ctrl+Shift+V

VS Code Integration

# Open current directory in VS Code
code .

---

Troubleshooting

WSL Won’t Start

# Check WSL status
wsl --status
 
# Re-register distro
wsl --unregister Ubuntu
wsl --install -d Ubuntu

DNS Not Working

1. Check /etc/resolv.conf exists and has nameservers
2. Try mirrored networking mode
3. Manually set DNS (see Custom resolv.conf section)

Slow File Access on /mnt/c

• Move projects to Linux filesystem: ~/projects/
• Exclude WSL directories from Windows Defender

Reset WSL Password

# Set root as default user
ubuntu config --default-user root
 
# Start WSL and reset password
wsl
passwd username
 
# Restore default user
ubuntu config --default-user username