.wslconfig vs. wsl.conf: Two Configuration Scopes That Should Not Be Mixed

WSL splits its configuration across two files with genuinely different scopes, and a large share of “why didn’t my setting take effect” confusion traces directly back to editing the wrong one, or expecting a setting scoped to one layer to affect the other.

.wslconfig: global, Windows-side, VM-wide

.wslconfig lives in the Windows user profile directory (%UserProfile%\.wslconfig) and controls settings for the shared WSL 2 virtual machine itself — memory allocation ceiling, processor count, swap size, the kernel image path, and networking mode among other VM-wide options. Because WSL 2 distributions share a single underlying utility VM rather than each getting their own separate virtual machine, every setting in .wslconfig applies to every distribution using that VM simultaneously — there’s no way to give one distribution more memory than another through this file, since the setting governs the shared VM as a whole, not any individual distribution within it.

/etc/wsl.conf: local, Linux-side, one distribution only

/etc/wsl.conf lives inside a specific distribution’s own filesystem and controls that distribution’s individual behavior — whether automount is enabled and how mounted drives are named, whether generated /etc/hosts and /etc/resolv.conf content is written at boot, the default user the distribution logs in as, the boot command or whether systemd is enabled as init, and various interop settings governing how Windows executables are invoked from within that distribution. Because this file lives inside a specific distribution’s filesystem, its settings are entirely local to that one distribution — a second distribution has its own separate /etc/wsl.conf, defaulting independently unless explicitly configured to match.

A concrete example of the confusion this causes

A common mistake: wanting to limit memory usage for one specific, particularly memory-hungry distribution, and looking for a memory setting inside that distribution’s /etc/wsl.conf. No such per-distribution memory setting exists, because memory is a .wslconfig-scoped, VM-wide resource — there is no mechanism to give one distribution a different memory ceiling than another while both share the same WSL 2 VM. The closest available control is the shared VM’s overall memory ceiling in .wslconfig, which constrains every distribution collectively, not any one distribution individually.

Why documented keys matter more than remembered ones

Both files’ supported keys have changed across WSL versions — a setting that existed in an older WSL release may be renamed, deprecated, or simply ignored in a newer one, and vice versa for newer settings not recognized by an older installed version. An unrecognized key in either file is typically silently ignored rather than producing a loud error, which means a typo or an outdated setting name can fail quietly, leaving you troubleshooting why a setting “isn’t working” when the actual problem is that WSL never recognized the key at all. Checking Microsoft’s current configuration documentation for your specific installed WSL version, rather than relying on a remembered setting name from an older article or a different version, avoids this specific, quiet failure mode.

What a minimal, well-scoped example of each actually looks like

# %UserProfile%\.wslconfig — affects the whole shared VM
[wsl2]
memory=8GB
processors=4
networkingMode=mirrored

# /etc/wsl.conf — affects only this one distribution
[boot]
systemd=true

[automount]
enabled=true
options="metadata"

[network]
generateResolvConf=false

Notice that memory and processor limits, and the networking mode, live exclusively in the Windows-side file, while systemd, automount behavior, and per-distribution DNS-file generation live exclusively in the Linux-side file — there’s no overlap where the same concern could correctly live in either location, which is precisely why “which file do I edit” has a definite answer once you know what you’re actually trying to change.

Why most changes to either file require a restart

Neither file is continuously watched for changes — both are read primarily at specific points in the startup sequence (VM creation for .wslconfig, distribution boot for wsl.conf), meaning a running instance generally won’t pick up an edit until it’s restarted:

wsl --shutdown

For .wslconfig changes specifically, this is a stronger requirement, since it affects the shared VM every distribution depends on — a full shutdown, not just restarting one distribution, is needed to guarantee the VM itself picks up the new global settings on next start.

Version both files, and comment why a non-default exists

Because these files directly govern behavior that’s easy to forget the reasoning behind months later — why memory was capped at a specific value, why automount was disabled for a specific distribution — keeping both files under version control (even a personal dotfiles repository) alongside a short comment explaining any non-default setting turns “I don’t remember why I set this” into a documented, recoverable decision. This matters especially on a machine other people might also need to administer, where the original reasoning otherwise exists only in one person’s memory.

Multi-distribution machines make the distinction unavoidable

The two-scope split becomes impossible to ignore the moment a machine runs more than one distribution regularly. A developer running both an Ubuntu distro for daily work and a separate Debian distro for a specific client project will have one .wslconfig governing memory and CPU for both, but two independent /etc/wsl.conf files, each configured according to that specific distribution’s own needs — one might enable systemd while the other doesn’t, one might have a different default user. Assuming a setting made in one distribution’s wsl.conf carries over to a newly created second distribution is a common and easily avoided mistake once the per-distribution scope is kept in mind.

Treat unknown or seemingly ineffective settings as a version question first

When a documented setting doesn’t seem to be taking effect, the fastest diagnostic step is confirming the installed WSL version actually supports it, via wsl --version, before assuming a syntax error or a deeper configuration problem — a genuinely correct setting for a newer WSL release simply won’t do anything on an older installation that predates it, and no amount of syntax troubleshooting will change that until the installation itself is updated. Related: How to Configure WSL2 Resource Limits with .wslconfig · Fixing a WSL Distro That Won’t Start or Hangs on ‘Installing’

Sources: