.wslconfig – Reference
Location: %UserProfile%\\.wslconfig (e.g. C:\\Users\\<You>\\.wslconfig)
Scope: Global — applies to all WSL 2 distributions
Apply changes:
wsl --shutdownthen relaunch
[wsl2] — VM Settings
| Key | Type | Default | Description |
|---|---|---|---|
kernel | path | MS inbox kernel | Custom Linux kernel |
kernelModules | path | — | Custom kernel modules VHD |
memory | size | 50% host RAM | VM memory limit |
processors | int | all logical CPUs | VM vCPU count |
swap | size | 25% RAM (rounded up GB) | Swap size; 0 = disabled |
swapFile | path | %Temp%\\swap.vhdx | Swap VHD location |
defaultVhdSize | size | 1 TB | Max distro filesystem VHD size |
localhostForwarding | bool | true | Expose WSL ports on Windows localhost |
kernelCommandLine | string | — | Extra kernel boot args |
guiApplications | bool | true | WSLg (GUI app support) |
safeMode | bool | false | Recovery mode — disables features |
debugConsole ¹ | bool | false | Show dmesg on distro start |
nestedVirtualization ¹ | bool | true | Allow nested VMs inside WSL |
vmIdleTimeout ¹ | int | 60000 | ms idle before VM auto-shutdown |
maxCrashDumpCount | int | 10 | Retained crash dumps |
networkingMode ¹² | string | NAT | nat · mirrored · virtioproxy · none · ~~bridged~~ |
firewall ¹² | bool | true | Apply Windows/Hyper-V firewall to WSL |
dnsProxy | bool | true | Point Linux DNS at host NAT (NAT mode only) |
dnsTunneling ¹² | bool | true | Tunnel DNS requests through Windows |
autoProxy ¹ | bool | true | Inherit Windows HTTP proxy settings |
[experimental] — Preview Features
| Key | Type | Default | Description |
|---|---|---|---|
autoMemoryReclaim | string | dropCache | disabled · gradual · dropCache |
sparseVhd | bool | false | Create new VHDs as sparse |
bestEffortDnsParsing ¹² | bool | false | Resolve DNS ignoring unknown records (dnsTunneling req.) |
dnsTunnelingIpAddress ¹² | string | 10.255.255.254 | Nameserver IP in resolv.conf (dnsTunneling req.) |
initialAutoProxyTimeout ¹ | string | 1000 | ms to wait for proxy info at startup (autoProxy req.) |
ignoredPorts ¹² | string | — | Comma-sep ports Linux can bind even if used on Windows (mirrored only) |
hostAddressLoopback ¹² | bool | false | Container ↔ host via host IPs, not just 127.0.0.1 (mirrored only) |
Value Format Rules
| Type | Format | Examples |
|---|---|---|
| path | Windows path, escaped backslashes | C:\\\\Temp\\\\myKernel |
| size | Number + unit (B default if omitted) | 8GB · 512MB · 1099511627776 |
| bool | true / false | |
| string | Plain text | vsyscall=emulate |
Footnotes
- ¹ Windows 11 only
- ² Requires Windows 11 22H2+
Starter Template
[wsl2] memory=8GB processors=4 swap=4GB localhostForwarding=true networkingMode=mirrored dnsTunneling=true firewall=true autoProxy=true nestedVirtualization=true # kernel=C:\\\\path\\\\to\\\\bzImage # kernelCommandLine=vsyscall=emulate # defaultVhdSize=256GB [experimental] autoMemoryReclaim=dropCache sparseVhd=true # bestEffortDnsParsing=false # ignoredPorts=3000,9000 # hostAddressLoopback=false
Source: Microsoft Learn — Advanced settings configuration in WSL (last updated 2025-08-06)
# recommended
Login
0 Comments
Oldest