Every .wslconfig Setting Explained
A plain-English reference to every .wslconfig setting for WSL 2: defaults, valid values, Windows version requirements and what each one changes.
The .wslconfig file controls the virtual machine that powers WSL 2: how much memory and how many processors it gets, which kernel it boots, and how it handles networking. This guide explains every setting Microsoft documents.
It follows Microsoft's Advanced settings configuration page, which was last updated on October 16, 2026, and checks it against Microsoft's release notes. Settings change between WSL releases, so confirm against the reference for your version.
The short answer
Create a file named .wslconfig in your Windows user folder, put settings under [wsl2], [general] or [experimental], then run wsl –shutdown and restart WSL. The most common settings are memory, processors and swap.
Microsoft recommends changing these in the WSL Settings app, found in the Start menu, instead of editing the file by hand. The file is still the way to set anything the app does not show.
Good to know
.wslconfig settings apply to WSL 2 distributions only. Settings for one distribution belong in a different file, wsl.conf, inside it.
Good to know
Verified on October 21, 2026 against Microsoft's reference, last updated October 16, 2026, and against WSL release notes through version 3.0.4, a pre-release published October 20, 2026. The latest stable release is 3.0.3.
How the .wslconfig file works
Location
Microsoft says it lives at %UserProfile%\.wslconfig, outside any Linux distribution.
Scope
It applies globally to every WSL 2 distribution, and Microsoft says global settings are available on Windows build 19041 and later.
Sections
Microsoft documents [wsl2] for main settings, [general] for general settings, and [experimental] for opt-in previews.
Applying changes
Microsoft says changes appear only after the WSL virtual machine fully stops and restarts, which typically takes about eight seconds.
To restart the machine quickly, run wsl –shutdown in PowerShell. Microsoft warns that it stops every running distribution, so save your work first.
Value formats
Sizes
Microsoft says size values default to bytes. Add a unit such as 8GB or 512MB.
Paths
Use absolute Windows paths and escape each backslash, as in C:\\Temp\\myCustomKernel.
Booleans
Use true or false.
Numbers
Time values are in milliseconds unless the setting says otherwise.
.wslconfig versus wsl.conf
| Aspect | .wslconfig | wsl.conf |
|---|---|---|
| Scope | All WSL 2 distributions | One distribution |
| Location | %UserProfile%\.wslconfig, outside Linux | /etc/wsl.conf, inside the distribution |
| Controls | The virtual machine: memory, processors, kernel, networking | The distribution: boot options, automounts, networking, interoperability, systemd and the default user |
| WSL versions | WSL 2 only | WSL 1 and WSL 2 |
Microsoft says wsl.conf supports automount, network, interop and user sections, plus a boot section for enabling systemd. Per-distribution settings need Windows build 17093 or later.
Resource settings in [wsl2]
memory
Default: 50% of Windows memory. Accepts: a size with a unit, such as 8GB. Needs: WSL 2. Sets how much memory the WSL 2 virtual machine can use.
processors
Default: Same as Windows logical processors. Accepts: a number. Needs: WSL 2. Sets how many logical processors the machine can use.
swap
Default: 25% of memory, rounded up to the nearest GB. Accepts: a size with a unit, such as 8GB. Needs: WSL 2. Adds disk-based memory for when demand exceeds the limit; 0 means no swap file.
swapFile
Default: swap.vhdx in your Temp folder. Accepts: an absolute Windows path. Needs: WSL 2. Chooses where the swap virtual hard disk is stored.
defaultVhdSize
Default: 1 TB. Accepts: a size with a unit, such as 8GB. Needs: WSL 2. Sets the size of the virtual disk that holds a distribution's file system, so it can cap how large that file system grows.
If vmmem is using too much memory, memory, swap and processors are the settings to change. Our guide to fixing vmmem high memory in WSL2 walks through them with a measuring method.
Kernel and boot settings in [wsl2]
kernel
Default: Microsoft's built kernel, supplied inbox. Accepts: an absolute Windows path. Needs: WSL 2. Points WSL at a custom Linux kernel.
kernelModules
Default: Not set. Accepts: an absolute Windows path. Needs: WSL 2. Points to a virtual hard disk of modules for a custom kernel.
kernelCommandLine
Default: None. Accepts: a string. Needs: WSL 2. Passes extra arguments to the kernel on boot.
loadDefaultKernelModules
Default: true. Accepts: true or false. Needs: WSL 2. Loads the three default kernel modules, tun, ip_tables and br_netfilter, at every boot of the machine.
loadKernelModules
Default: Null. Accepts: a string. Needs: WSL 2. Loads extra kernel modules from a comma-separated list.
kernelDebugPort
Default: 0. Accepts: a number. Needs: WSL 2. Sets the port for the kernel debugger relay; 0 turns kernel debugging off.
systemDistro
Default: The system distribution that ships with WSL. Accepts: an absolute Windows path. Needs: WSL 2. Points to a custom system distribution image, as an .img or .vhd file.
isolateDistroCgroup
Default: true. Accepts: true or false. Needs: WSL 2 with cgroup v2. Isolates each distribution in its own cgroup.
Microsoft's example sets kernelCommandLine to vsyscall=emulate to run older Linux base images such as CentOS 6. Most people never need the kernel settings, and a wrong value can stop WSL booting.
Networking settings in [wsl2]
localhostForwarding
Default: true. Accepts: true or false. Needs: WSL 2. Lets ports bound in the machine be reached from Windows at localhost:port.
dnsProxy
Default: true. Accepts: true or false. Needs: WSL 2. In NAT mode, points Linux DNS at the host's NAT; false copies Windows DNS servers instead.
networkingMode
Default: NAT. Accepts: none, nat, bridged (labelled deprecated), mirrored or consomme. Needs: Windows 11 22H2. Chooses how the machine connects: none, nat, bridged, mirrored or consomme.
firewall
Default: true. Accepts: true or false. Needs: Windows 11 22H2. Allows Windows Firewall and Hyper-V rules to filter WSL network traffic.
dnsTunneling
Default: true. Accepts: true or false. Needs: Windows 11 22H2. Changes the way WSL passes DNS requests on to Windows.
autoProxy
Default: true. Accepts: true or false. Needs: Windows 11. Has WSL pick up the HTTP proxy settings from Windows.
Networking modes explained
none
The WSL network is disconnected.
nat
The default. Starting from WSL 2.3.25, Microsoft says WSL falls back to Consomme mode if NAT mode fails.
bridged
Microsoft's reference calls it deprecated since WSL 2.4.5. The release notes give a more complicated history.
mirrored
Uses mirrored networking. Microsoft's example notes that localhostForwarding is ignored in this mode.
consomme
A further mode that Microsoft says was called virtioproxy in the past.
Release notes show 2.4.5 added a deprecation warning, 2.5.4 removed support and 2.5.6 brought it back. A September 2026 pre-release, 2.9.12, still fixed a bridged-mode configuration bug. Check the notes for your release.
An unknown value is treated as NAT. If localhost forwarding or DNS behaves oddly after a change, networkingMode is the first setting to check.
Feature settings in [wsl2]
guiApplications
Default: true. Accepts: true or false. Needs: WSL 2. Turns support for Linux GUI applications (WSLg) on or off.
gpuSupport
Default: true. Accepts: true or false. Needs: WSL 2. Turns GPU support in the virtual machine on or off.
nestedVirtualization
Default: true. Accepts: true or false. Needs: Windows 11. Lets other virtual machines run inside WSL 2.
virtiofs
Default: false. Accepts: true or false. Needs: WSL 2. Experimental. Uses VirtioFS for Windows filesystem shares, and needs virtio and hostFileSystemAccess enabled.
Lifecycle, timeout and diagnostic settings in [wsl2]
vmIdleTimeout
Default: 60000. Accepts: milliseconds. Needs: Windows 11. Sets milliseconds of idleness before the virtual machine shuts down.
kernelBootTimeout
Default: 30000. Accepts: milliseconds. Needs: WSL 2. Sets how long WSL waits for the kernel to start, in milliseconds.
distributionStartTimeout
Default: 60000. Accepts: milliseconds. Needs: WSL 2. Sets how long WSL waits for a distribution to start, in milliseconds.
mountDeviceTimeout
Default: 5000. Accepts: milliseconds. Needs: WSL 2. Sets how long WSL waits on disk operations when mounting or unmounting, in milliseconds.
debugConsole
Default: false. Accepts: true or false. Needs: Windows 11. Opens a console window showing dmesg when a distribution starts.
debugConsoleLogFile
Default: Not set. Accepts: an absolute Windows path. Needs: WSL 2. Writes Linux kernel console output to a file.
maxCrashDumpCount
Default: 10. Accepts: a number. Needs: WSL 2. Sets how many crash dump files are kept; older ones are deleted.
crashDumpFolder
Default: wsl-crashes in your Temp folder. Accepts: an absolute Windows path. Needs: WSL 2. Sets where crash dumps are stored.
telemetry
Default: on in official builds, off in others. Accepts: true or false. Needs: WSL 2. Turns WSL diagnostic telemetry on or off.
safeMode
Default: false. Accepts: true or false. Needs: Windows 11, WSL 0.66.2 or later. Runs WSL with many features disabled, to recover distributions in a bad state.
Settings in [general]
instanceIdleTimeout
Microsoft says it sets how many milliseconds a distribution sits idle before it is shut down. The default is 15000, and -1 disables automatic shutdown.
distributionInstallPath
Sets the default folder for newly installed distributions. The default is the wsl folder under %LocalAppData%.
Experimental settings
Microsoft calls these opt-in previews of features it hopes to turn on by default later. They live under [experimental].
autoMemoryReclaim
Default: dropCache. Accepts: disabled, gradual or dropCache. Needs: WSL 2. Returns cached memory to Windows: disabled, gradual (slowly) or dropCache (immediately).
sparseVhd
Default: false. Accepts: true or false. Needs: WSL 2. Makes any newly created virtual hard disk sparse automatically, an opt-in preview.
bestEffortDnsParsing
Default: false. Accepts: true or false. Needs: Windows 11 22H2. With dnsTunneling on, extracts the question from a DNS request and tries to resolve it, ignoring unknown records.
dnsTunnelingIpAddress
Default: 10.255.255.254. Accepts: a string. Needs: Windows 11 22H2. With dnsTunneling on, sets the nameserver written into resolv.conf.
initialAutoProxyTimeout
Default: 1000. Accepts: milliseconds. Needs: Windows 11. With autoProxy on, sets how long WSL waits for proxy information at start, in milliseconds.
ignoredPorts
Default: Null. Accepts: a string. Needs: Windows 11 22H2. In mirrored mode, lists ports Linux apps may bind to even if Windows uses them, such as 3000,9000,9090.
hostAddressLoopback
Default: false. Accepts: true or false. Needs: Windows 11 22H2. In mirrored mode, lets the host and container reach each other by any IPv4 address assigned to the host.
Microsoft's announcement says autoMemoryReclaim with gradual starts after five minutes of low CPU use and reclaims a fixed share each minute. Microsoft's reference lists dropCache as the current default.
Which Windows and WSL versions each setting needs
Windows 10 and Windows 11
Every setting without a footnote in Microsoft's reference, including memory, processors, swap, swapFile, defaultVhdSize, kernel, kernelCommandLine, localhostForwarding, dnsProxy and autoMemoryReclaim.
Windows 11 only
VmIdleTimeout, debugConsole, nestedVirtualization, autoProxy, initialAutoProxyTimeout and safeMode.
Windows 11 22H2 or later
NetworkingMode, firewall, dnsTunneling, bestEffortDnsParsing, dnsTunnelingIpAddress, ignoredPorts and hostAddressLoopback.
WSL release requirements
SafeMode needs WSL 0.66.2 or later, and instanceIdleTimeout appeared in 2.5.4. Run wsl –version to check yours.
Settings that depend on other settings
dnsProxy
Applies only when networkingMode is nat.
bestEffortDnsParsing and dnsTunnelingIpAddress
Apply only when dnsTunneling is true.
initialAutoProxyTimeout
Applies only when autoProxy is true.
ignoredPorts and hostAddressLoopback
Apply only in mirrored networking mode.
localhostForwarding
Microsoft's example says it is ignored in mirrored mode, and release notes show that behavior since 2.1.1.
virtiofs
It requires virtio and hostFileSystemAccess to be on. The reference documents neither, so it does not say where to set them.
isolateDistroCgroup
Requires cgroup v2.
loadKernelModules
Loads alongside the default modules unless loadDefaultKernelModules is false.
What the release notes add
Experimental networking settings
Release notes list experimental.networkingMode, firewall, dnsTunneling and autoProxy in 2.0.0, and say they moved to [wsl2] in 2.0.5.
autoMemoryReclaim
Release notes mention it from 1.3.10, with gradual, dropcache and disabled listed in 2.0.0.
instanceIdleTimeout
Release 2.5.4 introduced it as general.instanceIdleTimeout.
safeMode
Release 0.66.2 added it as wsl2.safeMode.
processors
Release 2.4.8 fixed a bug that made wsl2.processors always default to the maximum.
kernelBootTimeout
Release 2.4.4 made WSL respect the setting instead of a hardcoded 30 seconds.
Consomme
Release 2.3.25 added the fallback from NAT, and 2.9.3 renamed VirtioProxy to Consomme.
Sparse VHD
Release 2.5.6 put sparse VHD support behind an –allow-unsafe flag, and the 3.0.2 pre-release enabled experimental sparse VHD creation. The stable 3.0.3 no longer mentions the flag in its source.
pageReportingOrder
A 2023 option that release 1.1.7 removed, so it is not a current setting.
Settings most people change
memory and processors
They stop the virtual machine taking more of your PC than you want. They are the usual fix for a high vmmem number.
swap
Set it to 0 to remove the swap file, or raise it for memory-hungry builds.
autoMemoryReclaim
It returns cached memory to Windows when WSL is quiet.
networkingMode
Choose among none, nat, mirrored or consomme if the default network mode causes problems, on Windows 11 22H2 or later.
sparseVhd
It makes any newly created virtual disk sparse automatically.
defaultVhdSize
It caps how large a distribution's file system can grow.
Settings to leave alone unless you know why
kernel, kernelModules and kernelCommandLine
A wrong value can stop WSL booting.
safeMode
It disables many features, so use it only to recover a broken distribution.
systemDistro
It replaces the distribution WSL ships with.
The timeout settings
Raising them can hide a real startup problem instead of fixing it.
Our view: that last list is our advice, not Microsoft's. Microsoft documents what each setting does and does not rank them.
A starting file from Microsoft's own example
Microsoft's page includes a sample file. It limits memory to 4GB, uses two processors, sets swap to 8GB and turns on sparseVhd under [experimental].
| Line | What it means |
|---|---|
| [wsl2] | Starts the main settings section |
| memory=4GB | Limits the virtual machine to 4 GB of memory |
| processors=2 | Gives it two virtual processors |
| swap=8GB | Sets swap space to 8 GB |
| [experimental] | Starts the opt-in previews section |
| sparseVhd=true | Makes new virtual hard disks sparse |
Treat these values as an example, not a recommendation. Microsoft chose them to show the format, so size them to your own RAM and workload.
If a setting seems ignored
Wrong file name
Check the file is called .wslconfig and not .wslconfig.txt, and that it sits in your user folder.
Wrong section
Settings must sit under the right heading, such as [wsl2] or [experimental].
No restart
Run wsl –shutdown and wait about eight seconds before you start again.
Windows version
Settings marked Windows 11 only are not available on Windows 10.
Old WSL release
Run wsl –version, and update with wsl –update if the setting is newer than your release.
Microsoft's release notes show settings arriving in different releases, for example the experimental memory and networking settings in version 2.0.0. A key your release does not know can trigger an invalid key warning.
What Microsoft's reference does not say
Recommendations
It lists defaults and effects but does not recommend values.
Performance cost
It gives no figures for the effect of any setting.
Setting order
It does not say which settings override each other.
Some settings
The virtiofs entry mentions hostFileSystemAccess, which the table does not document.
Bridged networking
The reference calls it deprecated, while release notes show it was removed in 2.5.4 and brought back in 2.5.6.
Frequently asked questions
Where is the .wslconfig file?
Microsoft says it belongs in %UserProfile%\.wslconfig, outside any Linux distribution. It does not exist by default, so you create it.
Why is my .wslconfig change not applied?
WSL has to fully stop and restart. Run wsl –shutdown, wait about eight seconds, then start again.
Does .wslconfig affect WSL 1?
No. Microsoft says .wslconfig settings apply to WSL 2 distributions only.
What memory limit does WSL 2 use by default?
Microsoft's reference says 50 percent of your total Windows memory. Older guides quote 80 percent from earlier documentation.
Do I need Windows 11?
For some settings, yes. Microsoft marks vmIdleTimeout, nestedVirtualization, autoProxy and others as Windows 11 only, and some networking settings need Windows 11 22H2.
Can I use the WSL Settings app instead?
Yes, and Microsoft recommends it. It is in the Start menu. Hand-editing the file is still the way to set anything the app does not show.
Is bridged networking still supported?
Release notes show it was removed in 2.5.4 and brought back in 2.5.6, and a 2026 release still fixed its configuration. Microsoft's reference labels it deprecated, so check your release.
A quick checklist
From circuittimes.com/cloud-dev/every-wslconfig-setting-explained/
Was this guide helpful?
What went wrong?
Read nextComparison 13 min readGit Merge vs Rebase: When to Use Each, With Real ExamplesGit merge, rebase, fast-forward and squash compared with real command output, conflicts, force pushing and pull settings.
Comparison 11 min readJest vs Vitest: Which Test Runner to Use in 2026
Comparison 10 min readPlaywright vs Cypress: Which Testing Tool in 2026
Comparison 12 min readGitHub vs GitLab vs Bitbucket: Which to Choose in 2026
The briefing, without the noise.
The stories that matter in technology, every weekday morning.
Free. Unsubscribe in one click.