WSL autoMemoryReclaim: Choose a Mode with Controlled Measurements

The autoMemoryReclaim setting gives WSL 2 three documented choices for how cached guest memory is reclaimed: disabled, gradual, and dropCache. It is an experimental setting, so a value that looks attractive in a blog post should be evaluated against the workload it is meant to help. A single Task Manager screenshot cannot tell whether reclaimed memory came from Linux page cache, whether the workload suffered cache misses, or whether the VM’s effective pressure improved. Measure Windows and Linux state before changing the mode, test a repeatable workload, and keep the tradeoff explicit.

The current documented behavior

Microsoft lists autoMemoryReclaim in the [experimental] section of .wslconfig. The default is currently documented as dropCache; valid values are disabled, gradual, and dropCache. With disabled, WSL automatic memory reclamation is disabled. With gradual, cached memory is reclaimed slowly and automatically. With dropCache or an unknown value, cached memory is reclaimed immediately. The documentation describes these choices in terms of cached memory; it does not promise to shrink active process working sets, prevent an out-of-memory condition, or enforce a per-process limit.

Because the key remains in the experimental section, treat its behavior and defaults as versioned product behavior. Check wsl --version and the current Microsoft table when deploying it. The .wslconfig file is global to WSL 2 on the Windows account, so every distro sharing the VM may experience the selected behavior. It is not a per-distro setting, even if the symptom is first noticed in one distro.

The default has changed over time: Microsoft’s September 2023 announcement listed disabled, while the May 2024 update announced dropCache as the default in its then-current pre-release. Treat those posts as release history, not as a substitute for the live settings reference. An old tutorial can otherwise lead to a mistaken assumption about what an installation does when the key is omitted.

The distinction between Linux cache and application memory matters. Linux uses otherwise available RAM for caches, and that memory can often be reclaimed when a process needs it. Windows may show the WSL VM’s memory differently from Linux’s free output. A high host-side VM allocation does not by itself prove a leak; Linux’s available-memory and cache counters provide important context. Conversely, a mode that returns host memory more quickly can reduce cache warmth and change the next read-heavy workload’s latency.

Define a reproducible workload and baseline

Choose one workload that represents the observed problem: a build that scans many source files, a test suite, a container image operation, or an application with repeatable file reads. Record the WSL version, Windows build, .wslconfig, distro release, workload commit or input dataset, CPU load, and whether the run follows a cold or warm start. Do not compare a large package install under one mode with a small cached build under another.

Inside Linux, record memory counters before and after the workload:

free -h
grep -E '^(MemTotal|MemAvailable|Cached|Buffers|SwapTotal|SwapFree):' /proc/meminfo

If cgroup v2 is mounted for the distro and the workload has a known cgroup, capture its memory counters too. Those values answer a different question from the whole-VM view. Do not assume one distro’s free output accounts for every other distro or all host memory. On Windows, use a consistent tool and capture the WSL VM process memory together with total host availability and competing applications. Task Manager is a useful view, not the sole measurement source.

Define a service-level acceptance signal: build duration, test pass rate, p95 request latency, cache hit rate, or application health. Record at least several comparable runs for each mode and report the median and spread. Keep host power mode, VPN, other applications, and data set as consistent as practical. A single run is too sensitive to cache state and host background activity.

Configure one candidate mode at a time

The configuration form is:

[experimental]
autoMemoryReclaim=gradual

This example selects one documented value; it is not a universal recommendation. If .wslconfig already has an [experimental] section for sparse disks or DNS behavior, add the key to that section instead of creating duplicate headers. Do not change memory ceilings, swap, processors, sparse VHDs, and reclaim mode in the same experiment.

After editing, fully stop WSL so it loads the new setting. wsl --shutdown stops all running distributions and may interrupt services; quiesce databases and containers first. Restart the same distro and inspect Linux memory counters before reproducing the workload. The config value is intent. It is not runtime evidence that the feature is supported or that the test used the new setting.

Test gradual, dropCache, and disabled only if each choice is justified by a real decision. dropCache is the documented default today, but defaults may evolve. An explicit disabled setting can also override future defaults and keep memory reserved longer than expected. Do not treat the unknown-value fallback to dropCache as validation; a typo can silently behave like the aggressive mode according to current documentation.

Interpret results across host and guest layers

Track at least four dimensions:

Host memory available to Windows while WSL is idle and after the workload.
Linux MemAvailable, cache, and swap counters inside the distro.
The selected workload’s throughput or latency, including a second run that reveals cache effects.
Stability indicators such as process exits, OOM reports, application errors, and WSL startup behavior.

If Windows recovers more memory under one mode but the next filesystem-heavy run becomes slower, that is a real tradeoff rather than a contradiction. If Linux reports comfortable MemAvailable while Windows shows a large WSL process, capture both measurements and assess the actual host pressure. If swap rises, investigate the memory ceiling and workload demand; do not attribute every swap event to reclaim mode without a controlled comparison.

The mode cannot by itself establish whether memory belongs to an active process, a page cache, a container, or another distribution. Do not use echo 3 > /proc/sys/vm/drop_caches as a routine benchmark reset: manual cache dropping is a separate Linux intervention and changes the workload conditions. If a cold-cache experiment is required, define how it is created, record it identically for every test, and avoid combining it with automatic reclaim in the same trial.

Diagnose a setting that appears ineffective

Confirm the exact spelling and section, the active Windows user profile, WSL 2 version for the test distro, WSL package version, and a full restart. Keep one canonical .wslconfig; if WSL Settings or a provisioning script also edits it, inspect the final file after each change. Check the current docs because the key is experimental. A configured value in the file does not prove the runtime supports it.

If the mode appears to have no effect, first check whether the measurement actually shows reclaimable cached memory and whether the workload generates enough memory pressure to distinguish the policies. Compare an idle interval and a repeatable post-read phase; a short, low-memory command may not expose differences. Confirm that a Windows background workload did not dominate the host measurement. Avoid inferring feature behavior from a numeric vmmem value alone.

If a mode causes worse latency, errors, or instability, restore the previous setting or remove the override and restart WSL. Do not lower the VM memory ceiling or disable swap at the same time to “force” the experiment; that changes the failure mode. When a workload faces genuine memory exhaustion, inspect Linux OOM logs, process memory, swap, and cgroup limits separately, then adjust the resource design rather than assuming page-cache reclaim can solve active working-set pressure.

Decide whether an explicit value should remain

Keep an explicit setting only when a representative test shows a material, repeatable benefit that outweighs the cache or latency cost. Note whether the benefit is for host responsiveness, guest performance, or both. If the default meets the requirement, remove the key to inherit the current supported behavior. Revalidate after WSL upgrades, Windows updates, or workload changes; the same cache policy can have different effects on a repository build and a database.

For team or fleet configuration, store the test script, dataset identifier, WSL version, measurement output, selected value, owner, and review date. Alert on user-facing latency and host memory pressure rather than a single process-size threshold. Keep the config global scope visible in change review so a local experiment does not silently affect unrelated WSL services.

The acceptance gate is not “the option is set.” It is that the runtime version is known, the same workload was measured under controlled conditions, host and guest counters are interpreted together, the user-facing metric is acceptable, and rollback is straightforward. This turns an experimental setting into an evidence-based local operating choice rather than cargo-cult memory tuning.

Related:

Sources: