How to Configure WSL2 Resource Limits with .wslconfig

.wslconfig is the global configuration file controlling WSL2’s virtual machine settings across every installed distro — this walks through the settings you’re most likely to actually need.

Step 1: locate (or create) the file

%UserProfile%\.wslconfig

This file doesn’t exist by default — create it directly in your Windows user profile folder if it isn’t already there.

Step 2: understand this applies platform-wide, not per-distro

Unlike /etc/wsl.conf, which configures settings for one specific distro, .wslconfig configures the entire WSL2 virtual machine platform — its settings apply uniformly across every distro you have installed.

Step 3: set a memory ceiling

[wsl2]
memory=4GB

This caps the maximum RAM the WSL2 VM can ever claim — useful for preventing unbounded vmmem growth while leaving enough for your actual workloads.

Step 4: set a processor count limit

[wsl2]
processors=4

Limits how many logical processors the WSL2 VM can use — useful on a machine where you want to guarantee some CPU headroom remains available for Windows-side applications running concurrently.

Step 5: configure swap space

[wsl2]
swap=2GB
swapFile=C:\\wsl-swap.vhdx

WSL2 uses a swap file for virtual memory beyond the configured RAM limit — adjusting its size, or its location (useful if you want it on a specific, faster drive), is controlled here.

Step 6: set the networking mode

[wsl2]
networkingMode=mirrored

Switches between the default NAT-based networking and mirrored networking mode, which gives WSL2 the same network configuration as the Windows host directly.

Step 7: control whether WSL2 starts automatically

[wsl2]
autoMemoryReclaim=gradual

This setting influences how proactively WSL2 attempts to release unused memory back to Windows over time, rather than only on explicit request.

Step 8: apply changes by restarting WSL2 completely

wsl --shutdown

Every .wslconfig change requires this full shutdown-and-restart step to take effect — editing the file alone has no immediate effect on an already-running WSL2 VM.

Step 9: verify your settings actually applied

# from inside a distro, after restart:
free -h    # confirm the memory ceiling
nproc      # confirm the processor count

Why centralizing these settings in one file makes sense

Because every WSL2 distro shares the same underlying virtual machine (a consequence of WSL2’s architecture), resource limits genuinely are a platform-wide concern rather than a per-distro one — .wslconfig’s single, centralized configuration reflects that shared-VM reality accurately, rather than requiring redundant, potentially conflicting per-distro settings for something that’s actually one shared resource pool.