`.wslconfig` vs `wsl.conf`: which file sets what in WSL

windows - 2026-11-01

I hadn't used a graphical Linux desktop since Mandrake, a Linux distribution from the late 1990s and early 2000s later renamed Mandriva. Linux has been terminals and servers for me since. So when a graphical tool wouldn't open in WSL2, I first looked for its switch in the wrong configuration file. This entry is the map I was missing.

WSL (Windows Subsystem for Linux) runs Linux distributions on Windows. WSL2, its current version, runs every distribution inside one shared, lightweight virtual machine. Two configuration files tune it, at two different levels, and a setting only works in the file that defines it (Microsoft's WSL configuration page).

	`%USERPROFILE%\.wslconfig`	`/etc/wsl.conf`
Lives	on Windows, in your user profile (`C:\Users\<you>\.wslconfig`)	inside each distribution
Applies to	every WSL2 distribution, because they share one virtual machine	that distribution only, WSL1 or WSL2
Exists by default	no	depends on the distribution
Sections	`[wsl2]`, `[experimental]`	`[automount]`, `[network]`, `[interop]`, `[user]`, `[boot]`, `[gpu]`, `[time]`
Examples	`memory`, `processors`, `networkingMode`, `guiApplications`, `gpuSupport`	`systemd`, `appendWindowsPath`, `hostname`, `[gpu] enabled`
Takes effect	after `wsl --shutdown`	once the distribution has fully stopped

Both use the INI format: a [section] line, then key=value lines. If a file is missing or malformed, WSL starts anyway without its settings.

Neither file overrides the other

The two files have different keys, so for almost every setting the question of which one wins doesn't come up. A setting placed in the wrong file is just not one of that file's keys. For example, WSLg, the part of WSL2 that shows Linux graphical applications as Windows windows, is turned on or off by guiApplications in .wslconfig only. wsl.conf has no key for it, so WSLg can't be turned off for one distribution and kept for another. The docs don't say what WSL does with a guiApplications line written in wsl.conf by mistake.

The GPU is the one feature both files have a say in, at two levels:

.wslconfig, [wsl2] gpuSupport: GPU support in the WSL2 virtual machine, so for every distribution.
wsl.conf, [gpu] enabled: whether Linux applications in this distribution can reach the Windows GPU, and [gpu] appendLibPath, which adds /usr/lib/wsl/lib to PATH.
wsl.conf, [automount] ldconfig: adds the GPU libraries Windows provides to the search path of the dynamic loader (the part of Linux that finds shared libraries when a program starts) and runs ldconfig to refresh its cache. It concerns those GPU libraries only.

All of them default to true. The docs don't state a precedence between the two files. They do say ldconfig "only applies to WSL 2 with GPU support enabled", and since every distribution runs in the same virtual machine, the likely reading is that gpuSupport=false leaves no GPU for any distribution's wsl.conf to enable. That reading wasn't tested here.

When a change takes effect

.wslconfig is read when the virtual machine starts, so stop it from PowerShell or a Windows terminal, then open the distribution again:

wsl --shutdown

That stops every running distribution.

wsl.conf is read when the distribution starts. A distribution keeps running for a few seconds after its last shell closes, so closing the terminal and reopening it right away can still find the old settings. Check, or stop just that one:

wsl --list --running
wsl --terminate Ubuntu

Microsoft also suggests changing the global settings in the WSL Settings app from the Start menu rather than editing .wslconfig by hand.

An example of each

# %USERPROFILE%\.wslconfig: the virtual machine, every distribution
[wsl2]
guiApplications=true

# /etc/wsl.conf: this distribution only
[boot]
systemd=true

[interop]
appendWindowsPath=false

systemd=true starts systemd as the distribution's init process (the first process, which starts services). appendWindowsPath=false stops WSL from adding the Windows PATH to the Linux one, so Windows programs are no longer found by name from the Linux shell.

Sources

Microsoft Learn, Advanced settings configuration in WSL, from MicrosoftDocs/WSL (WSL/wsl-config.md), fetched 2026-11-01.
The examples are the files from a working Ubuntu 26.04.1 setup under WSL2. Nothing here ran in the Linux cloud container where this entry was drafted, which isn't WSL.

Created 2026-11-01T17:25:06+01:00 · Edit