Master .wslconfig: Fine‑Tune Memory, CPU, and Disk for WSL2

.wslconfig Overview

The .wslconfig file is the global configuration for Windows Subsystem for Linux (WSL) 2. Editing this INI‑style file controls resource limits, swap, networking mode, and disk settings for all installed distributions.

File Location and Format

Path: C:\Users\<your‑username>\.wslconfig Format: Windows INI (same syntax as .ini files). Changes become effective after running wsl --shutdown.

Basic Structure

[wsl2]
memory=8GB
processors=6

Full Parameter Details

1. Resource Management

memory – Memory limit

# Format
memory=<size>
# Examples
memory=4GB        ; fixed 4 GB
memory=50%         ; 50 % of total RAM (default)
memory=8192MB      ; MB syntax
memory=0           ; unlimited (not recommended)

8 GB total RAM → memory=4GB (half for Windows)

16 GB total RAM → memory=8GB 32 GB+ total RAM → memory=16GB (large projects / Docker)

64 GB+ total RAM → memory=24GB (AI/ML workloads)

processors – CPU core limit

# Format
processors=<core‑count>
# Examples
processors=6      ; use 6 cores
processors=4      ; keep half for Windows
processors=-1    ; use all cores

Recommendation: Reserve 2‑4 cores for Windows to avoid lag when switching out of WSL.

swap – Swap space

swap=2GB          ; fixed 2 GB
swap=0            ; disable (if RAM is sufficient)
swap=auto         ; default: 25 % of RAM, max 4 GB
swapfile=D:\wsl-swap.swap   ; custom location to save C: space

vmIdleTimeout – Automatic memory reclamation

vmIdleTimeout=-1   ; never reclaim (default, best performance)
vmIdleTimeout=600  ; reclaim after 10 min idle
vmIdleTimeout=3600 ; reclaim after 1 h idle

When reclamation is enabled, memory usage gradually drops after the idle period.

2. Network Parameters (Key Section)

networkingMode – Network mode selection

# Options
networkingMode=NAT        ; default, backward compatible
networkingMode=mirrored  ; mirrored mode (recommended on Windows 11)
networkingMode=symmetric ; symmetric NAT (advanced)

NAT : Requires manual localhost configuration, no LAN access, isolated virtual IPv4, limited IPv6, average VPN compatibility, works on Windows 10/11.

mirrored : Automatic localhost connectivity, LAN access, shares Windows IPv4 address, full IPv6, best VPN compatibility, recommended for Windows 11.

symmetric : Supports localhost and LAN, optional IPv4, IPv6 present, good VPN compatibility, works on latest Windows 11.

mirrored mode additional options

networkingMode=mirrored
dnsTunneling=true   ; resolve DNS via Windows (fixes DNS issues)
autoProxy=true      ; inherit Windows proxy settings automatically
firewall=true        ; enable Windows firewall isolation

Tip for Windows 11 users: Copy the block above directly into .wslconfig for optimal networking.

3. Disk and Mount Parameters

defaultVHDSize – Initial VHDX size

defaultVHDSize=60GB   ; initial maximum size (grows on demand)

kernelCommandLine – Kernel boot parameters (advanced)

kernelCommandLine="net.ifnames=0 biosdevname=0"   ; unify network interface naming

Recommended Configuration Schemes

Scheme 1 – Balanced Development (most developers)

[wsl2]
memory=8GB
swap=4GB
swapfile=D:\wsl-swap.swap
processors=6
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true
vmIdleTimeout=-1

Scheme 2 – Light‑Weight (8 GB RAM or laptops)

[wsl2]
memory=4GB
swap=2GB
processors=4
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
vmIdleTimeout=-1

Scheme 3 – High‑Performance (16 GB+ RAM, heavy Docker use)

[wsl2]
memory=12GB
swap=4GB
processors=10
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true
vmIdleTimeout=-1

Scheme 4 – AI/ML Training (32 GB+ RAM, GPU)

[wsl2]
memory=24GB
swap=8GB
processors=14
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
vmIdleTimeout=-1

Applying Configuration Changes

1. Edit C:\Users\<your‑username>\.wslconfig
2. Save the file
3. In PowerShell run: wsl --shutdown
4. Re‑open your Linux distribution
5. Verify:
   free -h      # memory
   nproc        # CPU cores

Note: Use a semicolon ; for comments in .wslconfig , not the hash # .

Advanced Tips

Tip 1 – Quick Switch Between Multiple Configurations

Create separate config files (e.g., .wslconfig.dev, .wslconfig.light, .wslconfig.heavy) and copy the desired file to .wslconfig before restarting WSL.

# Example PowerShell function (add to $PROFILE)
function Set-WSLConfig {
    param([string]$Profile="dev")
    $src = "$env:USERPROFILE\.wslconfig.$Profile"
    if (Test-Path $src) {
        Copy-Item $src "$env:USERPROFILE\.wslconfig" -Force
        wsl --shutdown
        Write-Host "Switched to $Profile config and restarted WSL"
    }
}
# Usage: Set-WSLConfig heavy

Tip 2 – Monitor Actual Resource Usage

Run inside WSL:

echo "=== CPU ==="
nproc
echo "=== Memory ==="
free -h
echo "=== Disk ==="
df -h /
echo "=== Top Processes ==="
ps aux --sort=-%mem | head -8

Run in PowerShell to inspect the Vmmem process:

Get-Process Vmmem | Select-Object CPU, WorkingSet64, @{N='Mem_MB';E={[math]::Round($_.WorkingSet64/1MB)}}