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.

Current installs can use WSL Settings

Microsoft now recommends the WSL Settings application, available from the Start menu, for changing global WSL 2 options. It works with the same configuration model and respects existing .wslconfig values; it is not a second per-distribution configuration layer. The text file remains useful for reviewed, reproducible workstation setup, while the GUI makes supported options and defaults easier to discover.

Whichever interface owns the configuration, do not alternate an old provisioning script and manual GUI changes without comparing the resulting state. The WSL Settings guide explains its relationship to .wslconfig, /etc/wsl.conf, enterprise policy, and rollback.

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: choose automatic memory reclaim deliberately

[experimental]
autoMemoryReclaim=gradual

This setting lives under [experimental] rather than the main [wsl2] section. Current Microsoft documentation lists dropCache as the default, with gradual and disabled as alternatives. gradual releases cached memory after idle detection over time; dropCache reclaims cached page cache more directly. A hand-written gradual value is therefore a measured alternative, not a universally required fix for every current installation.

Check wsl --version and Microsoft’s current key documentation before overriding the default. Memory returned to Windows, Linux cache hit rate, swap activity, and workload latency should all be part of the comparison.

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: