Skip to content
WSLDeep Dive Published Updated 4 min readViews unavailable

WSL 2 Swap Files: Capacity, Placement, and Safe Configuration

Configure WSL 2 swap through global .wslconfig settings, understand its VHD backing file, and verify guest behavior after restart.

WSL 2 runs Linux distributions inside a virtual machine. Its swap setting controls disk-backed swap available to that VM; it is separate from the VM’s memory limit and from the Windows page file. Changing one does not automatically resize the others, and adding swap is not a substitute for diagnosing a memory leak or a workload that exceeds its intended budget.

Microsoft documents .wslconfig as a global configuration file for all WSL 2 distributions. The documented default swap size is 25 percent of Windows memory, rounded up to the nearest gigabyte, and the default backing path is a swap VHD under the user’s temporary directory. The swap setting can be zero to disable the WSL swap file. Confirm current behavior against the installed WSL version and the current Microsoft documentation before relying on defaults.

Configure the VM-level setting

The file belongs in the Windows user profile, not inside a Linux distribution’s /etc directory. wsl.conf has per-distribution scope; .wslconfig controls VM settings globally across WSL 2 distributions. Keep the distinction explicit so a change intended for one distro does not unexpectedly affect every distro sharing the VM.

[wsl2]
memory=8GB
swap=4GB
swapFile=C:\\WSL\\swap.vhdx

The values above are an example, not a sizing recommendation. Use an absolute Windows path for swapFile, ensure the target directory exists and is writable by the user running WSL, and reserve enough host-disk space. Avoid placing a growing backing file on a removable or unreliable volume. If you set swap=0, you disable WSL’s swap file; this can make memory exhaustion fail sooner rather than making the workload use less memory.

Apply changes and verify from both sides

Configuration changes take effect when the WSL 2 virtual machine starts. Microsoft notes that running wsl –shutdown may be needed to stop the VM before the new values are applied. This terminates running WSL distributions, so save work and coordinate long-running services first.

After restarting, inspect the guest with free -h and swapon --show --bytes, and compare the reported swap capacity with the intended setting. swapon --show reports configured active swap devices; /proc/swaps is another guest-side view. On Windows, verify that the configured path is valid and that the backing VHD is on the expected volume. Guest swap capacity, the host-side VHD’s allocated size, and Windows page-file configuration are different measurements; one does not directly report the others.

The setting is VM-wide, not per distribution. Two WSL 2 distributions sharing the VM see the same memory and swap policy, so swap=4GB is not a reservation of four gigabytes for each distro. It is also not a guaranteed additional four gigabytes of usable application memory: guest-kernel overhead, workload behavior, host disk capacity, and applicable memory limits still matter. A process or container can fail under pressure before a workload reaches a simple sum of the configured RAM and swap values.

Diagnose pressure instead of masking it

Swap can keep some workloads operating through a transient memory spike, but disk-backed paging is much slower than RAM and can increase latency. If the guest spends sustained time swapping, inspect per-process memory, cache behavior, workload concurrency, and the configured WSL VM memory limit. A service that becomes unresponsive under pressure may need a lower concurrency cap, a leak fix, or a different resource limit, not just a larger swap VHD.

Establish a baseline before changing the file. Record wsl --version, wsl --list --verbose, the current .wslconfig, guest free -h, swapon --show --bytes, and Windows free space on the target volume. Repeat the same workload after the VM restart. Keep the test bounded and comparable: a larger swap value can make an out-of-memory failure happen later while still making response time worse.

Measure before and after a change: guest MemAvailable, swap use, process or cgroup memory, host commit pressure, and storage latency. For a time series, run vmstat 1 during a reproducible workload and compare repeated interval rows; the first report summarizes activity since boot, while subsequent reports use the requested interval. Sustained nonzero swap-in/swap-out activity together with latency is more actionable than a single cumulative swap-used number. If only one distribution needs a different allocation, remember that .wslconfig cannot express per-distro VM memory limits. Do not delete the VHD while WSL may be using it; stop the VM cleanly and use the documented WSL lifecycle before moving or removing its backing file.

Define an acceptance condition before editing, such as “the same build completes without guest OOM and p95 build time remains within the agreed budget.” If it fails, restore the previous .wslconfig, stop WSL cleanly, relaunch, and verify the prior guest swap total returned. This distinguishes a configuration rollback from a workload or storage problem that remains after the VM setting is restored.

Document the previous configuration, planned values, shutdown impact, verification commands, and rollback. A safe change has a known host-disk location, a tested restart, and a clear signal for whether the workload improved.

Related:

Sources:

Comments