WSL Settings: A GUI for the Same Configuration Model as .wslconfig

WSL Settings provides a Windows interface for the global options that govern the WSL 2 virtual machine. Microsoft now recommends modifying those options through the Settings app, available from the Start menu, instead of manually editing every value in %UserProfile%\.wslconfig.

The GUI does not introduce a second hidden configuration system. It reads and writes the same global model, while existing .wslconfig settings remain respected. That compatibility makes migration convenient, but it also means invalid or duplicated hand-written sections can still affect what the app displays and saves.

Global and per-distribution scopes remain separate

WSL uses two configuration files with different owners:

%UserProfile%\.wslconfig controls the WSL 2 VM shared by the user’s distributions;
/etc/wsl.conf controls behavior inside one distribution.

Global options include VM memory, processor count, swap, kernel path, networking mode, DNS tunneling, firewall integration, proxy behavior, and experimental features. Per-distribution options include automount behavior, Windows interoperability, the default user, boot commands, and systemd enablement.

WSL Settings operates on the global side. It cannot make a distribution-specific systemd=true choice without editing that distribution’s /etc/wsl.conf, and a setting inside Ubuntu cannot limit the VM memory shared with Debian.

Before changing anything, export the current text file and record the WSL version:

wsl --version
Copy-Item "$HOME\.wslconfig" "$HOME\.wslconfig.backup" -ErrorAction SilentlyContinue

The backup is a review aid, not a reason to restore obsolete values blindly after an update.

Prefer defaults unless a measured problem exists

The Settings app makes options discoverable, which can encourage unnecessary tuning. A memory ceiling can protect Windows responsiveness but also force Linux reclaim or out-of-memory kills. A custom processor count can make a benchmark repeatable but slow build systems that expect all available cores.

Change one category at a time and record the reason. For resource settings, capture Windows memory, WSL memory, swap activity, build time, and application errors before and after. For networking, test DNS, localhost reachability, VPN behavior, IPv6, inbound firewall policy, and corporate proxy access.

Do not disable the WSL firewall or DNS tunneling merely because one application fails. Those defaults integrate WSL with current Windows networking. Find whether the actual problem is a blocked port, an unsupported VPN, a stale resolver file, or a service listening only on loopback.

Apply VM changes with a controlled shutdown

Global changes take effect when the WSL 2 VM restarts. Close editors and shells, stop databases cleanly inside each distribution, then run:

wsl --list --running
wsl --shutdown

Starting the next WSL command recreates the VM with the new configuration. wsl --shutdown is not an application-aware database stop. Quiesce stateful workloads first so a settings change does not become an unclean recovery test.

After restart, verify the effective result from both sides. Check wsl --status or wsl --version on Windows, then inspect CPU count, memory, routes, resolvers, and the intended service from Linux. A value visible in the GUI is configuration intent; guest behavior is the acceptance test.

Keep manual edits structurally valid

Some workflows still use .wslconfig in source-controlled workstation setup. Use INI sections exactly as documented, keep one authoritative entry per key, and use escaped Windows paths where required.

[wsl2]
memory=8GB
processors=4
firewall=true
dnsTunneling=true

WSL continues to launch when the file is absent. A malformed file may cause settings to be ignored or rewritten in surprising ways, so reopen WSL Settings after an automated edit and confirm that it can parse the result. Never alternate an old provisioning script and the GUI without deciding which is authoritative.

Experimental settings deserve version checks. Options move from preview to default or change behavior as Store-delivered WSL evolves independently of a Windows feature update. Link each managed value to the documentation version used when approving it.

Enterprise policy can constrain the UI

Intune and Group Policy settings can disable WSL, block WSL 1 or the inbox version, restrict commands such as debug shell and disk mounting, and prevent users from overriding selected .wslconfig values. WSL Settings cannot legitimately bypass those controls.

If a field is unavailable on a managed device, inspect policy and WSL version before repairing the app. A user-configurable laptop and a locked enterprise workstation can show different valid interfaces.

Roll back the smallest possible change

If WSL fails after editing, compare the new configuration with the backup and remove only the suspect key. A missing .wslconfig returns global behavior to defaults; deleting a distribution, its VHD, or its package is unnecessary and destructive.

Keep a recovery sequence outside WSL: edit or rename the Windows-side file, run wsl --shutdown, start one distribution, and verify data before re-enabling other integrations. The GUI makes configuration easier to discover, but a text backup and a measured rollback remain the fastest path when the VM cannot start.

Detect drift between intent and effective state

The configuration file, Settings screen, and running VM describe three moments. A saved value is intended state; the GUI is another editor for that state; CPU count, memory, routes, DNS, and mounted filesystems inside the VM are effective state. Compare all three after an update rather than assuming a successful save restarted WSL.

Closing one terminal is not sufficient because another distribution, background service, editor integration, or container engine can keep the shared VM alive. wsl --list --running shows the visible distribution state, while wsl --shutdown provides the explicit restart boundary. Stop databases and other stateful services first, then timestamp the shutdown and next start so logs belong to the correct generation.

For managed configuration, generate one canonical .wslconfig, hash it, and record the WSL version used to validate it. After the Settings app or provisioning tool changes the file, compare the normalized keys rather than line order. Unknown or newly defaulted options should trigger review, not automatic deletion, because Store WSL evolves separately from the host’s feature update cadence.

Build a small acceptance script that captures host WSL version and running distributions, then queries guest CPU count, memory, swap, resolver, routes, and a test connection. Keep secrets and full proxy URLs out of that artifact. A configuration change is complete when the intended value survives a real VM restart and the workloads it was meant to help still pass, not when the control is visible in the Settings window.

Related:

Sources: