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: enable more proactive automatic memory reclaim

[experimental]
autoMemoryReclaim=gradual

This experimental setting, which lives under [experimental] rather than the main [wsl2] section, makes the VM proactively release cached memory back to Windows after detecting idle CPU usage, rather than holding onto everything until the VM fully shuts down. gradual releases cached memory slowly over time; dropcache releases it more aggressively and immediately. Without this setting, cached memory stays allocated to the WSL2 VM until you explicitly shut it down — worth setting deliberately if you’ve observed vmmem holding onto reclaimable cache longer than you’d like between active work sessions.

A minimal, complete example combining several settings

# %UserProfile%\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=2GB
networkingMode=mirrored

[experimental]
autoMemoryReclaim=gradual

Combining settings this way in a single file is the normal, expected usage — there’s no need to apply them one at a time, and grouping related settings together with a comment explaining any non-default choice makes the file considerably easier to review later.

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.

Checking which settings are documented for your specific WSL version

.wslconfig’s supported keys have grown over successive WSL releases, and experimental settings in particular (like autoMemoryReclaim above) can move, get renamed, or graduate out of the experimental section entirely in a later release. Before assuming a setting from an older article or answer no longer works, check it against Microsoft’s current documentation for the specific key name and section, and confirm your installed version with wsl --version — an unrecognized key is typically ignored silently rather than producing an error, which means a stale setting name can fail quietly rather than obviously.

Rolling back a change that made things worse

If a specific .wslconfig change causes problems rather than solving them — a memory ceiling set too aggressively, a networking mode that breaks a specific VPN — the rollback is simply removing or commenting out the offending line and running wsl --shutdown again. Keeping the file under version control, even informally in a personal dotfiles repository, makes it trivial to see exactly what changed and revert precisely that change rather than reconstructing the previous working configuration from memory.

Test one change at a time when troubleshooting a specific problem, rather than adjusting several settings simultaneously — isolating which single change actually fixed (or caused) a given behavior is nearly impossible once multiple settings changed at once.

Confirming the file’s location and encoding are actually correct

A .wslconfig file created accidentally with a .txt extension appended by Windows Explorer’s default file-saving behavior, or saved with an unexpected text encoding, is silently ignored rather than producing an error — if none of your settings appear to take effect at all despite a careful edit, confirming the file’s exact name and location (%UserProfile%\.wslconfig, with no additional extension) directly in a terminal rather than trusting Explorer’s file listing view is worth doing before assuming a specific setting is unsupported.

Related:

Sources: