The Only .wslconfig Guide You Need (Memory/CPU/Swap For Stability)

If you’ve ever watched your laptop’s fans spin up during a build, seen Windows apps slow to a crawl while Docker compiles in the background, or found WSL2 gobbling 80% of your RAM “for no reason,” this guide is for you. The Only .wslconfig Guide You Need (Memory/CPU/Swap for Stability) shows how to tame and tune WSL2’s resource usage using a single file: your global .wslconfig. You’ll learn what each setting means, how to pick values that match your hardware, and how to fix common problems like DNS failures, slow Git operations, ext4.vhdx disk bloat, and sluggish file I/O. By the end, you’ll have a stable, fast, developer-friendly WSL2 setup that plays nicely with the rest of Windows.

H2: The Only .wslconfig Guide You Need (Memory/CPU/Swap for Stability): Overview
WSL2 runs your Linux distributions inside a lightweight VM. By default, it dynamically grows its memory usage and can use all your CPU cores, which is great for peak performance but can hurt overall system stability and battery life. That’s where the global configuration file, C:\Users\\.wslconfig, comes in.

In plain English, .wslconfig is how you:

– Put a ceiling on how much RAM WSL2 can use.
– Limit how many CPU cores the VM gets.
– Control swap (size and file location) to avoid thrashing.
– Opt into newer networking and disk behavior.
– Adjust idle/shutdown behaviors to reclaim resources.

Typical scenarios where .wslconfig helps:

– Docker Desktop on WSL2 causes high memory usage or swap storms during builds.
– Large Node.js/Java/C++ compiles make Windows apps lag or the system thermally throttle.
– Running databases (PostgreSQL, MySQL, MongoDB) in WSL2 consumes RAM over time.
– Git on large repos is slow, especially when files live on /mnt/c.
– WSL2 disks (ext4.vhdx) grow and don’t shrink automatically; space pressure increases.

H2: Quick Reference Table

H2: Key Concepts & Prerequisites

H3: What .wslconfig is (and isn’t)
– .wslconfig is a Windows-side, user-level file that configures the WSL2 VM globally for all distributions.
– It uses INI-style sections ([wsl2], [experimental]).
– It is not the same as /etc/wsl.conf (which configures behavior inside a specific Linux distro such as user, mounts, and resolv.conf generation).
– Changes to .wslconfig require wsl –shutdown (or a reboot) to take effect.

H3: Requirements
– Windows 11 or Windows 10 version 2004 (build 19041) or later.
– WSL2 installed. If needed:
– Enable features (run in elevated PowerShell):
– dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
– dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
– Install WSL from the Microsoft Store (recommended):
– wsl –install
– Virtualization enabled in BIOS/UEFI (Intel VT-x, AMD-V).
– Optional: Hyper-V PowerShell module for VHD optimization (Windows Pro/Enterprise; Home users may need to enable the Hyper-V module feature).

H3: Where the files live
– Global config: C:\Users\\.wslconfig
– Linux distro disks: %LOCALAPPDATA%\Packages\\LocalState\ext4.vhdx
– Systemwide Docker for WSL2: docker-desktop and docker-desktop-data distributions.

H2: Step-by-Step Guide

H3: 1) Confirm and update your WSL2
– Open PowerShell, then:

wsl –status
wsl –version
wsl –update

– Ensure your distributions are WSL2:

wsl –list –verbose
wsl –set-version 2
wsl –set-default-version 2

Why: Newer WSL releases add important features (better memory reclaim, mirrored networking, sparse VHD, bug fixes).

H3: 2) Decide your resource targets
Before editing .wslconfig, choose sane limits based on your hardware and workload. Guidelines:

– Memory:
– 16 GB RAM PC: memory=6GB to 10GB for mixed Windows+Linux workflows; 50% if you do heavy builds but still need Windows responsiveness.
– 32 GB+ RAM: memory=12GB to 18GB for heavy builds; up to 75% for dedicated dev sessions.
– Laptops on battery: err on the conservative side (e.g., 6–8GB).
– Don’t set memory too low for Docker or large compiles; you’ll trigger swap thrash.

– CPUs:
– Use processors=50–75% of cores for general dev work.
– Use processors=All only when Windows workload is minimal.

– Swap:
– swap=0 disables swap (fastest but risk of OOM kills on spikes).
– 4–8GB swap is a safe default for most devs.
– Put swapFile on a fast disk (default is fine; NVMe is ideal).
– Avoid massive swap sizes; swap is a band-aid, not a replacement for RAM.

H3: 3) Create or edit .wslconfig with recommended templates
Open the file:

notepad %UserProfile%\.wslconfig

Option A — Balanced (most users)

[wsl2]
memory=8GB
processors=6
swap=8GB
swapFile=C:\\Users\\%USERNAME%\\wsl-swap.vhdx
localhostForwarding=true
nestedVirtualization=false
vmIdleTimeout=600

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true

Option B — Battery-friendly (laptop, meetings, light coding)

[wsl2]
memory=6GB
processors=4
swap=4GB
localhostForwarding=true
vmIdleTimeout=300

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true

Option C — Heavy builds (short sprints)

[wsl2]
memory=50%
processors=All
swap=8GB
localhostForwarding=true

[experimental]
autoMemoryReclaim=dropcache
sparseVhd=true
networkingMode=mirrored

Notes:
– memory accepts fixed sizes (e.g., 8GB) or a percentage (e.g., 50%).
– processors can be an integer or “All”.
– swap controls the size; swapFile lets you relocate it (use escaped backslashes).
– vmIdleTimeout is seconds before the VM is shut down when idle.
– [experimental] options require a modern Store WSL; unsupported keys are safely ignored. networkingMode=mirrored improves localhost and service discovery (great for dev), dnsTunneling and autoProxy help with corporate networks, sparseVhd helps disk compaction, autoMemoryReclaim improves memory return to Windows.

H3: 4) Apply and verify
– Apply changes:

wsl –shutdown

– Start your distro and verify:

free -h
cat /proc/meminfo | grep MemTotal
nproc
cat /proc/swaps
uname -r
ip addr

You should see MemTotal near your memory limit, nproc matching your processors setting, and the swap file present if configured.

H3: 5) Docker Desktop with WSL2: sanity check
– In Docker Desktop Settings:
– Use WSL2 backend and enable integration for your distro(s).
– Note: With the WSL2 backend, Docker resource limits are governed by .wslconfig, not Docker Desktop’s old Hyper-V sliders.
– Best practices:
– Keep project source, bind mounts, and build contexts inside the Linux filesystem (e.g., /home//src) rather than /mnt/c to avoid I/O penalties.
– Use BuildKit:

export DOCKER_BUILDKIT=1
docker build .

– For large builds, consider increasing memory or temporarily reducing parallelism (e.g., — cpus flag in docker run or target-specific build flags).

H3: 6) Advanced: know what you cannot do
– There’s no per-distro memory/CPU limit (settings in .wslconfig apply to the whole VM hosting all WSL2 distros).
– Per-distro settings (e.g., default user, mount options, resolv.conf behavior) belong in /etc/wsl.conf, not .wslconfig.

H2: Troubleshooting

H3: DNS not working in WSL2
Symptoms: apt update fails, ping hostname works inconsistently, corporate VPN breaks name resolution.

Fix A: Let WSL generate resolv.conf (default)
– Ensure /etc/wsl.conf has:

[network]
generateResolvConf=true

– Remove any custom /etc/resolv.conf:

sudo rm -f /etc/resolv.conf

– Apply:

wsl –shutdown

Fix B: Provide a static resolv.conf (e.g., behind strict VPNs/proxies)
– In /etc/wsl.conf:

[network]
generateResolvConf=false

– Create /etc/resolv.conf:

sudo tee /etc/resolv.conf >/dev/null << 'EOF' nameserver 1.1.1.1 nameserver 8.8.8.8 options edns0 EOF - Then: wsl --shutdown ipconfig /flushdns netsh winsock reset If you use [experimental] networkingMode=mirrored with dnsTunneling=true, many DNS issues improve automatically. H3: Git is slow on large repos - Do not work on /mnt/c. Move the repo: # inside WSL mkdir -p ~/workspace mv /mnt/c/Users//source/myrepo ~/workspace/myrepo

– Speed up Git metadata operations:

cd ~/workspace/myrepo
git config core.fileMode false
git config core.untrackedCache true
git config gc.auto 256
git config fetch.writeCommitGraph true
git config commitGraph.generationVersion 2

– Avoid massive untracked directories; consider .gitignore hygiene.
– If using file watchers, keep watchers in Linux (e.g., run Node/webpack watchers inside WSL, not from Windows).

H3: Disk space bloat: ext4.vhdx won’t shrink
WSL2 VHD grows but doesn’t shrink automatically. To compact:

1) Free space inside Linux (delete caches, prune Docker):

sudo apt-get clean
docker system prune -af
sudo rm -rf ~/.cache/*

2) Shutdown WSL:

wsl –shutdown

3) Compact the VHD (PowerShell, with Hyper-V module):

# Replace path with your distro’s ext4.vhdx
Optimize-VHD -Path “$env:LOCALAPPDATA\Packages\\LocalState\ext4.vhdx” -Mode Full

Tip: With newer WSL, [experimental] sparseVhd=true can improve ongoing disk space reclamation.

H3: File I/O slowness
– Avoid /mnt/c, /mnt/d for builds, node_modules, or databases. Use the native Linux filesystem under your distro (e.g., ~, /var/lib).
– If you must work with Windows files, reduce chattiness (fewer small files, fewer watchers) and cache aggressively (e.g., pnpm store, yarn cache).
– For databases, keep data directories on the Linux filesystem (e.g., /var/lib/postgresql/data).

H3: High CPU usage or thermal throttling
– Reduce processors in .wslconfig or use a fixed value rather than All.
– Ensure no runaway processes: top, htop.
– Consider autoMemoryReclaim=gradual and vmIdleTimeout to release resources when idle.
– On laptops, prefer balanced profiles and consider disabling nestedVirtualization.

H3: Swap thrashing (system feels frozen)
– Increase memory in .wslconfig or reduce parallelism of builds.
– If you must keep memory low, set swap to a small but non-zero value (e.g., 4–8GB) and ensure the swapFile sits on fast storage.
– Optionally lower Linux swappiness:

echo “vm.swappiness=10” | sudo tee /etc/sysctl.d/99-wsl.conf
sudo sysctl -p /etc/sysctl.d/99-wsl.conf

H2: Optimization & Best Practices

H3: Filesystem placement and paths
– Keep active development trees, node_modules, virtualenvs, and databases inside your Linux home or /opt, not on /mnt/c.
– Use \\wsl$ from Windows apps to access Linux files when needed (e.g., VS Code Remote – WSL extension handles this seamlessly).

H3: Memory and CPU tuning patterns
– Start conservative, observe with htop/free -h, then iterate.
– For heavy compiles or Docker builds, temporarily increase memory; afterward, revert for battery life and Windows responsiveness.
– Use autoMemoryReclaim=gradual (if available) to return memory to Windows without forcing restarts.

H3: Caching and installs
– Node.js: use pnpm or yarn with a shared store under Linux; keep caches local to WSL.
– Python: use venvs in Linux; pip cache in ~/.cache/pip.
– Docker: keep images/volumes within docker-desktop-data (default for WSL2). Prune regularly.

H3: Networking reliability
– If you frequently switch networks or VPNs, use [experimental] networkingMode=mirrored and dnsTunneling=true.
– If corporate proxies are involved, autoProxy=true can help propagate settings.

H3: Disk hygiene
– Prune Docker images/containers weekly (docker system prune -af).
– Delete big caches regularly (language-specific).
– Periodic VHD optimization if you delete lots of data.

H3: Tooling tips
– Use VS Code’s “Remote – WSL” extension to keep file operations in Linux.
– Consider asdf/pyenv/nvm under Linux for language runtimes to avoid Windows path overhead.
– Keep WSL itself updated: wsl –update.

H2: Project-Based Example: Stable Node.js builds with Dockerized PostgreSQL

Scenario: You have a Node.js monorepo using Docker for Postgres and Redis, with frequent yarn build and jest test runs. On default WSL2, your Windows desktop lags, RAM usage spikes to 90%, and builds sometimes thrash on swap.

Step 1: Pick a balanced .wslconfig
– 16 GB machine, aim for stability:

[wsl2]
memory=8GB
processors=6
swap=8GB
localhostForwarding=true
vmIdleTimeout=600

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true
networkingMode=mirrored
dnsTunneling=true

Step 2: Apply and verify
– wsl –shutdown
– Inside the distro:

free -h # Shows ~8GB RAM
nproc # Shows 6
cat /proc/swaps # Shows 8GB swap

Step 3: Ensure filesystem placement
– Move repo into WSL:

mkdir -p ~/workspace
mv /mnt/c/Users//source/my-monorepo ~/workspace/
cd ~/workspace/my-monorepo

Step 4: Improve Node/Docker flow
– Enable BuildKit:

export DOCKER_BUILDKIT=1

– Start services:

docker compose up -d postgres redis

– Run builds and tests inside WSL:

yarn install –immutable
yarn build -w packages/*
yarn test

– Add Git optimizations:

git config core.fileMode false
git config core.untrackedCache true

Step 5: Measure sanity
– During builds, watch top/htop: CPU under control (6 cores), memory steady near 6–7GB with headroom, minimal swapping.
– Windows stays responsive. Browser, Teams/Slack remain smooth.

Step 6: Weekly maintenance
– docker system prune -af
– Clear language caches as appropriate
– wsl –shutdown, then Optional VHD compact using Optimize-VHD for reclaimed disk space

H2: Conclusion
WSL2 can be both fast and reliable—with the right caps in place. The Only .wslconfig Guide You Need (Memory/CPU/Swap for Stability) showed you how to bound RAM, CPU, and swap; adopt modern networking; and keep disks from ballooning. When you place projects inside the Linux filesystem, tune cache and build strategies, and use a reasonable .wslconfig, you get predictable performance and a cooler, quieter machine. Update WSL regularly, iterate your settings based on real workloads, and enjoy a smooth cross-OS development experience.

H2: FAQ

H4: Where do I put .wslconfig and how do I apply changes?
Put it in C:\Users\\.wslconfig. After editing, run wsl –shutdown to restart the WSL2 VM so changes take effect.

H4: What’s the difference between .wslconfig and /etc/wsl.conf?
.wslconfig is a Windows-side, global file controlling the VM (memory, CPUs, swap, networking mode). /etc/wsl.conf is per-distro, controlling Linux-side behavior like default user, mounts, and resolv.conf generation.

H4: Is it safe to set swap=0 for performance?
It can be, but risky. Builds may fail with out-of-memory errors. For most devs, 4–8GB swap is a safer balance. If you disable swap, increase memory to avoid OOM during peaks.

H4: Can I set limits per distribution (e.g., give Ubuntu 8GB but Debian 4GB)?
Not currently. .wslconfig limits apply to the single WSL2 VM hosting all distros. You can still optimize per distro using app-level settings (e.g., database buffers, build parallelism).

H4: My ext4.vhdx is huge even after deletions—how do I shrink it?
Free space inside the distro (clean caches, prune Docker), wsl –shutdown, then run Optimize-VHD on the ext4.vhdx from PowerShell with the Hyper-V module. With newer WSL, [experimental] sparseVhd=true helps ongoing space reclamation.

You’ve got this. With a thoughtful .wslconfig and a few workflow tweaks, WSL2 becomes a stable, high‑performance foundation for everyday development.

The Only .wslconfig Guide You Need (Memory/CPU/Swap for Stability)

About the author

Jonathan Dudamel

About the author

Jonathan Dudamel

You may also like