.wslconfig vs wsl.conf — Understanding WSL2's Two Configuration Files¶
Audience: Developers using WSL2 who need clarity on which config file to edit
Key Points¶
- .wslconfig = VM-level control Lives on Windows side; manages memory, CPU, and network mode
- wsl.conf = Per-distro settings Lives in Linux /etc/; manages systemd, mounts, and users
- Same reload method Both require
wsl --shutdownthen restart
Decide in 1 Minute: Which File Do You Need?¶
When you want to change a WSL2 setting, the choice between .wslconfig and wsl.conf can be confusing.
The rule is simple. Is it a setting for the VM (virtual machine) itself, or for the Linux running inside it? To limit RAM to 4GB, use .wslconfig. To enable systemd, use wsl.conf. Their roles are completely separate.
| Aspect | .wslconfig | /etc/wsl.conf |
|---|---|---|
| Location | Windows: C:\Users\<Name>\.wslconfig | Linux: /etc/wsl.conf |
| Scope | All distros (global) | That distro only (local) |
| Controls | VM itself (CPU, RAM, networking) | Distro behavior (mounts, systemd, user) |
| WSL 1 support | No (WSL 2 only) | Yes (WSL 1 and 2) |
This table covers 80% of cases. Let's look at specific settings.
.wslconfig — Control the VM from Windows¶
.wslconfig doesn't exist by default. Create it manually at C:\Users\<UserName>\.wslconfig.
Key Settings¶
Write settings under the [wsl2] section.
[wsl2]
memory=4GB
processors=2
swap=2GB
localhostForwarding=true
nestedVirtualization=true
| Key | Default | Description |
|---|---|---|
memory | 50% of physical RAM | Memory allocated to the VM |
processors | All logical processors | CPU cores for the VM |
swap | 25% of physical RAM | Swap size. 0 to disable |
localhostForwarding | true | Expose WSL ports on Windows localhost |
networkingMode | NAT | Network mode (see below) |
nestedVirtualization | true | Allow VMs inside WSL |
The most common use case is RAM limiting. WSL2 takes 50% of physical memory by default — on an 8GB machine, that's 4GB claimed by WSL. Setting memory=4GB keeps the host OS responsive.
Mirrored Mode (Windows 11 22H2+)¶
If WSL2 networking is unstable under VPN, networkingMode=mirrored helps.
[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true
Mirrored mode mirrors Windows network interfaces directly into Linux. DNS issues under VPN and proxy environments improve significantly.
Experimental Section¶
Memory reclaim and VHD auto-shrink are available as experimental features.
[experimental]
autoMemoryReclaim=gradual
sparseVhd=true
autoMemoryReclaim=gradual releases cached memory incrementally when idle. Effective on memory-constrained machines.
/etc/wsl.conf — Configure Each Distro from Linux¶
wsl.conf may not exist by default. Create or edit it with sudo nano /etc/wsl.conf.
Sections and Settings¶
[boot]
systemd=true
[user]
default=devuser
[automount]
enabled=true
options="metadata,umask=022"
[network]
generateResolvConf=false
[interop]
enabled=true
appendWindowsPath=true
| Section | Key Settings | Purpose |
|---|---|---|
[boot] | systemd=true, command | Enable systemd, run commands at boot |
[user] | default=<username> | Change default login user |
[automount] | enabled, root, options | Windows drive mount config |
[network] | generateResolvConf, generateHosts | Control DNS/hosts auto-generation |
[interop] | enabled, appendWindowsPath | Windows interop settings |
The "per-distro" scope matters when you run multiple distributions. You can have different default users and systemd settings for Ubuntu and Debian.
Common Configuration Examples¶
Disable auto-generated DNS and use custom DNS:
[network]
generateResolvConf=false
After this, create /etc/resolv.conf manually:
sudo rm /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf
This fixes name resolution failures under corporate DNS or VPN environments.
Change Windows drive mount point:
[automount]
root=/
The default /mnt/c becomes /c. Shorter paths, but watch for compatibility with existing scripts.
How to Apply Changes¶
The same procedure applies regardless of which file you changed.
wsl --shutdown
Then reopen WSL. Simply closing the terminal isn't enough — WSL background processes linger for about 8 seconds. wsl --shutdown ensures a clean stop.
To restart only a specific distro:
wsl --terminate Ubuntu
Summary¶
.wslconfigis VM-wide,wsl.confis per-distro — remember this and you'll never mix them up- RAM, CPU, network mode go in
.wslconfig; systemd, users, mounts go inwsl.conf - Both need
wsl --shutdownto apply
If changes don't take effect, first make sure you ran wsl --shutdown. If it still doesn't work, check the file location. Putting .wslconfig inside Linux or wsl.conf on the Windows side is a surprisingly common mistake.