Advanced settings configuration in WSL
The wsl.conf and .wslconfig files are used to configure advanced settings in WSL that will be applied on start up of the WSL VM. wsl.conf is used to apply settings on a per WSL distro basis, and .wslconfig is used to apply global settings to WSL. You can read more about the differences below.
Aspect.wslconfig``wsl.confScopeGeneral settings that apply to all of WSLSettings for WSL distributions onlyConfiguresFeature enablement in WSL, settings for the virtual machine powering WSL 2 (RAM, kernel to boot, number of CPUs, etc.)Distribution settings in WSL such as boot options, DrvFs automounts, networking, interoperability with the Windows system, systemd usage, and default userLocation%UserProfile%\.wslconfig, outside of a WSL distribution/etc/wsl.conf, while inside a WSL distribution
Currently, all .wslconfig settings apply only to WSL 2 distributions. Learn how to check which version of WSL you are running.
The 8 second rule for configuration changes
You must wait until the subsystem running your Linux distribution completely stops running and restarts for configuration setting updates to appear. This typically takes about 8 seconds after closing ALL instances of the distribution shell.
If you launch a distribution (e.g. Ubuntu), modify the configuration file, close the distribution, and then re-launch it, you might assume that your configuration changes have immediately gone into effect. This is not currently the case as the subsystem could still be running. You must wait for the subsystem to stop before relaunching in order to give enough time for your changes to be picked up. You can check to see whether your Linux distribution (shell) is still running after closing it by using PowerShell with the command: wsl --list --running. If no distributions are running, you will receive the response: "There are no running distributions." You can now restart the distribution to see your configuration updates applied.
The command wsl --shutdown is a fast path to restarting WSL 2 distributions, but it will shut down all running distributions, so use wisely. You can also use wsl --terminate <distroName> to terminate a specific distribution that's running instantly.
wsl.conf
Configure local settings with wsl.conf per-distribution for each Linux distribution running on WSL 1 or WSL 2.
- Stored in the
/etcdirectory of the distribution as a unix file. - Used to configure settings on a per-distribution basis. Settings configured in this file will only be applied to the specific Linux distribution that contains the directory where this file is stored.
- Can be used for distributions run by either version, WSL 1 or WSL 2.
- To get to the
/etcdirectory for an installed distribution, use the distribution's command line withcd /to access the root directory, thenlsto list files orexplorer.exe .to view in Windows File Explorer. The directory path should look something like:/etc/wsl.conf.
Note
Adjusting per-distribution settings with the wsl.conf file is only available in Windows Build 17093 and later.
Configuration settings for wsl.conf
The wsl.conf file configures settings on a per-distribution basis. (For global configuration of WSL 2 distributions see .wslconfig).
The wsl.conf file supports four sections: automount, network, interop, and user. (Modeled after .ini file conventions, keys are declared under a section, like .gitconfig files.) See wsl.conf for info on where to store the wsl.conf file.
systemd support
Many Linux distributions run "systemd" by default (including Ubuntu) and WSL has recently added support for this system/service manager so that WSL is even more similar to using your favorite Linux distributions on a bare metal machine. You will need version 0.67.6+ of WSL to enable systemd. Check your WSL version with command wsl --version. If you need to update, you can grab the latest version of WSL in the Microsoft Store. Learn more in blog announcement.
To enable systemd, open your wsl.conf file in a text editor using sudo for admin permissions and add these lines to the /etc/wsl.conf:
[boot]
systemd=true
You will then need to close your WSL distribution using wsl.exe --shutdown from PowerShell to restart your WSL instances. Once your distribution restarts, systemd should be running. You can confirm using the command: systemctl list-unit-files --type=service, which will show the status of your services.
Automount settings
wsl.conf section label: [automount]
keyvaluedefaultnotesenabledbooleantrue``true causes fixed drives (i.e C:/ or D:/) to be automatically mounted with DrvFs under /mnt. false means drives won't be mounted automatically, but you could still mount them manually or via fstab.mountFsTabbooleantrue``true sets /etc/fstab to be processed on WSL start. /etc/fstab is a file where you can declare other filesystems, like an SMB share. Thus, you can mount these filesystems automatically in WSL on start up.rootstring/mnt/Sets the directory where fixed drives will be automatically mounted. By default this is set to /mnt/, so your Windows file system C-drive is mounted to /mnt/c/. If you change /mnt/ to /windir/, you should expect to see your fixed C-drive mounted to /windir/c.optionscomma-separated list of values, such as uid, gid, etc, see automount options belowempty stringThe automount option values are listed below and are appended to the default DrvFs mount options string. Only DrvFs-specific options can be specified.
The automount options are applied as the mount options for all automatically mounted drives. To change the options for a specific drive only, use the /etc/fstab file instead. Options that the mount binary would normally parse into a flag are not supported. If you want to explicitly specify those options, you must include every drive for which you want to do so in /etc/fstab.
Automount options
Setting different mount options for Windows drives (DrvFs) can control how file permissions are calculated for Windows files. The following options are available:
KeyDescriptionDefaultuidThe User ID used for the owner of all filesThe default User ID of your WSL distro (on first installation this defaults to 1000)gidThe Group ID used for the owner of all filesThe default group ID of your WSL distro (on first installation this defaults to 1000)umaskAn octal mask of permissions to exclude for all files and directories022``fmaskAn octal mask of permissions to exclude for all files000``dmaskAn octal mask of permissions to exclude for all directories000``metadataWhether metadata is added to Windows files to support Linux system permissionsdisabled``caseDetermines directories treated as case sensitive and whether new directories created with WSL will have the flag set. See case sensitivity for a detailed explanation of the options. Options include off, dir, or force.off
By default, WSL sets the uid and gid to the value of the default user. For example, in Ubuntu, the default user is uid=1000, gid=1000. If this value is used to specify a different gid or uid option, the default user value will be overwritten. Otherwise, the default value will always be appended.
User file-creation mode mask (umask) sets permission for newly created files. The default is 022, only you can write data but anyone can read data. Values can be changed to reflect different permission settings. For example, umask=077 changes permission to be completely private, no other user can read or write data. To further specify permission, fmask (files) and dmask (directories) can also be used.
Note
The permission masks are put through a logical OR operation before being applied to files or directories.
What is DrvFs?
DrvFs is a filesystem plugin to WSL that was designed to support interop between WSL and the Windows filesystem. DrvFs enables WSL to mount drives with supported file systems under /mnt, such as /mnt/c, /mnt/d, etc. For more information about specifying the default case sensitivity behavior when mounting Windows or Linux drives or directories, see the case sensitivity page.
Network settings
wsl.conf section label: [network]
keyvaluedefaultnotesgenerateHostsbooleantrue``true sets WSL to generate /etc/hosts. The hosts file contains a static map of hostnames corresponding IP address.generateResolvConfbooleantrue``true sets WSL to generate /etc/resolv.conf. The resolv.conf contains a DNS list that are capable of resolving a given hostname to its IP address.hostnamestringWindows hostnameSets hostname to be used for WSL distribution.
Interop settings
wsl.conf section label: [interop]
These options are available in Insider Build 17713 and later.
keyvaluedefaultnotesenabledbooleantrueSetting this key will determine whether WSL will support launching Windows processes.appendWindowsPathbooleantrueSetting this key will determine whether WSL will add Windows path elements to the $PATH environment variable.
User settings
wsl.conf section label: [user]
These options are available in Build 18980 and later.
keyvaluedefaultnotesdefaultstringThe initial username created on first runSetting this key specifies which user to run as when first starting a WSL session.
Boot settings
The Boot setting is only available on Windows 11 and Server 2022.
wsl.conf section label: [boot]
keyvaluedefaultnotescommandstring""A string of the command that you would like to run when the WSL instance starts. This command is run as the root user. e.g: service docker start.
Example wsl.conf file
The wsl.conf sample file below demonstrates some of the configuration options available. In this example, the distribution is Ubuntu-20.04 and the file path is \\wsl.localhost\Ubuntu-20.04\etc\wsl.conf.
# Automatically mount Windows drive when the distribution is launched
[automount]
# Set to true will automount fixed drives (C:/ or D:/) with DrvFs under the root directory set above. Set to false means drives won't be mounted automatically, but need to be mounted manually or with fstab.
enabled = true
# Sets the directory where fixed drives will be automatically mounted. This example changes the mount location, so your C-drive would be /c, rather than the default /mnt/c.
root = /
# DrvFs-specific options can be specified.
options = "metadata,uid=1003,gid=1003,umask=077,fmask=11,case=off"
# Sets the `/etc/fstab` file to be processed when a WSL distribution is launched.
mountFsTab = true
# Network host settings that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, preventing WSL from the default behavior of auto-generating /etc/hosts, and sets generateResolvConf to false, preventing WSL from auto-generating /etc/resolv.conf, so that you can create your own (ie. nameserver 1.1.1.1).
[network]
hostname = DemoHost
generateHosts = false
generateResolvConf = false
# Set whether WSL supports interop processes like launching Windows apps and adding path variables. Setting these to false will block the launch of Windows processes and block adding $PATH environment variables.
[interop]
enabled = false
appendWindowsPath = false
# Set the user when launching a distribution with WSL.
[user]
default = DemoUser
# Set a command to run when a new WSL instance launches. This example starts the Docker container service.
[boot]
command = service docker start
.wslconfig
Configure global settings with .wslconfig across all installed distributions running on WSL.
- The .wslconfig file does not exist by default. It must be created and stored in your
%UserProfile%directory to apply these configuration settings. - Used to configure settings globally across all installed Linux distributions running as the WSL 2 version.
- Can be used only for distributions run by WSL 2. Distributions running as WSL 1 will not be affected by this configuration as they are not running as a virtual machine.
- To get to your
%UserProfile%directory, in PowerShell, usecd ~to access your home directory (which is typically your user profile,C:\Users\<UserName>) or you can open Windows File Explorer and enter%UserProfile%in the address bar. The directory path should look something like:C:\Users\<UserName>\.wslconfig.
WSL will detect the existence of these files, read the contents, and automatically apply the configuration settings every time you launch WSL. If the file is missing or malformed (improper markup formatting), WSL will continue to launch as normal without the configuration settings applied.
Configuration settings for .wslconfig
The .wslconfig file configures settings globally for all Linux distributions running with WSL 2. (For per-distribution configuration see wsl.conf).
See .wslconfig for info on where to store the .wslconfig file.
Note
Configuring global settings with .wslconfig are only available for distributions running as WSL 2 in Windows Build 19041 and later. Keep in mind you may need to run wsl --shutdown to shut down the WSL 2 VM and then restart your WSL instance for these changes to take effect.
This file can contain the following options that affect the VM that powers any WSL 2 distribution:
Main WSL settings
.wslconfig section label: [wsl2]
keyvaluedefaultnoteskernelpathThe Microsoft built kernel provided inboxAn absolute Windows path to a custom Linux kernel.kernelModulespathAn absolute Windows path to a custom Linux kernel modules VHD.memorysize50% of total memory on WindowsHow much memory to assign to the WSL 2 VM.processorsnumberThe same number of logical processors on WindowsHow many logical processors to assign to the WSL 2 VM.localhostForwardingbooleantrueBoolean specifying if ports bound to wildcard or localhost in the WSL 2 VM should be connectable from the host via localhost:port.kernelCommandLinestringBlankAdditional kernel command line arguments.safeModebooleanfalseRun WSL in "Safe Mode" which disables many features and is intended to be used to recover distributions that are in bad states. Only available for Windows 11 and WSL version 0.66.2+.swapsize25% of memory size on Windows rounded up to the nearest GBHow much swap space to add to the WSL 2 VM, 0 for no swap file. Swap storage is disk-based RAM used when memory demand exceeds limit on hardware device.swapFilepath%USERPROFILE%\AppData\Local\Temp\swap.vhdxAn absolute Windows path to the swap virtual hard disk.pageReportingbooleantrueDefault true setting enables Windows to reclaim unused memory allocated to WSL 2 virtual machine.guiApplicationsbooleantrueBoolean to turn on or off support for GUI applications ( WSLg) in WSL.debugConsole*booleanfalseBoolean to turn on an output console Window that shows the contents of dmesg upon start of a WSL 2 distro instance. Only available for Windows 11.nestedVirtualization*booleantrueBoolean to turn on or off nested virtualization, enabling other nested VMs to run inside WSL 2. Only available for Windows 11.vmIdleTimeout*number60000The number of milliseconds that a VM is idle, before it is shut down. Only available for Windows 11.dnsProxybooleantrueOnly applicable to networkingMode = NAT. Boolean to inform WSL to configure the DNS Server in Linux to the NAT on the host. Setting to false will mirror DNS servers from Windows to Linux.networkingMode**stringNATIf the value is mirrored then this turns on mirrored networking mode. Default or unrecognized strings result in NAT networking.firewall**booleantrueSetting this to true allows the Windows Firewall rules, as well as rules specific to Hyper-V traffic, to filter WSL network traffic.dnsTunneling**booleantrueChanges how DNS requests are proxied from WSL to WindowsautoProxy*booleantrueEnforces WSL to use Windows’ HTTP proxy informationdefaultVhdSizesize1099511627776 (1TB)Set the Virtual Hard Disk (VHD) size that stores the Linux distribution (for example, Ubuntu) file system. Can be used to limit the maximum size that a distribution file system is allowed to take up.
Entries with the path value must be Windows paths with escaped backslashes, e.g: C:\\Temp\\myCustomKernel
Entries with the size value must be a size followed by a unit, for example, 8GB or 512MB.
Entries with an * after the value type are only available on Windows 11.
Entries with an ** after the value type require Windows 11 version 22H2 or higher.
Experimental settings
These settings are opt-in previews of experimental features that we aim to make default in the future.
.wslconfig section label: [experimental]
Setting nameValueDefaultNotesautoMemoryReclaimstringdropCacheAutomatically releases cached memory after detecting idle CPU usage. Set to gradual for slow release, and dropCache for instant release of cached memory.sparseVhdboolfalseWhen set to true, any newly created VHD will be set to sparse automatically.bestEffortDnsParsing**boolfalseOnly applicable when wsl2.dnsTunneling is set to true. When set to true, Windows will extract the question from the DNS request and attempt to resolve it, ignoring the unknown records.dnsTunnelingIpAddress**string10.255.255.254Only applicable when wsl2.dnsTunneling is set to true. Specifies the nameserver that will be configured in the Linux resolv.conf file when DNS tunneling is enabled.initialAutoProxyTimeout*string1000Only applicable when wsl2.autoProxy is set to true. Configures how long (in milliseconds) WSL will wait for retrieving HTTP proxy information when starting a WSL container. If proxy settings are resolved after this time, the WSL instance must be restarted to use the retrieved proxy settings.ignoredPorts**stringnullOnly applicable when wsl2.networkingMode is set to mirrored. Specifies which ports Linux applications can bind to, even if that port is used in Windows. This enables applications to listen on a port for traffic purely within Linux, so those applications are not blocked even when that port is used for other purposes on Windows. For example, WSL will allow binding to port 53 in Linux for Docker Desktop, as it is listening only to requests from within the Linux container. Should be formatted in a comma separated list, e.g: 3000,9000,9090``hostAddressLoopback**boolfalseOnly applicable when wsl2.networkingMode is set to mirrored. When set to True, will allow the Container to connect to the Host, or the Host to connect to the Container, by an IP address that's assigned to the Host. The 127.0.0.1 loopback address can always be used,this option allows for all additionally assigned local IP addresses to be used as well. Only IPv4 addresses assigned to the host are supported.
Entries with an * after the value type are only available on Windows 11.
Entries with an ** after the value type require Windows version 22H2 or higher.
Example .wslconfig file
The .wslconfig sample file below demonstrates some of the configuration options available. In this example, the file path is C:\Users\<UserName>\.wslconfig.
# Settings apply across all Linux distros running on WSL 2
[wsl2]
# Limits VM memory to use no more than 4 GB, this can be set as whole numbers using GB or MB
memory=4GB
# Sets the VM to use two virtual processors
processors=2
# Specify a custom Linux kernel to use with your installed distros. The default kernel used can be found at https://github.com/microsoft/WSL2-Linux-Kernel
kernel=C:\\temp\\myCustomKernel
# Specify the modules VHD for the custum Linux kernel to use with your installed distros.
kernelModules=C:\\temp\\modules.vhdx
# Sets additional kernel parameters, in this case enabling older Linux base images such as Centos 6
kernelCommandLine = vsyscall=emulate
# Sets amount of swap storage space to 8GB, default is 25% of available RAM
swap=8GB
# Sets swapfile path location, default is %USERPROFILE%\AppData\Local\Temp\swap.vhdx
swapfile=C:\\temp\\wsl-swap.vhdx
# Disable page reporting so WSL retains all allocated memory claimed from Windows and releases none back when free
pageReporting=false
# Turn on default connection to bind WSL 2 localhost to Windows localhost. Setting is ignored when networkingMode=mirrored
localhostforwarding=true
# Disables nested virtualization
nestedVirtualization=false
# Turns on output console showing contents of dmesg when opening a WSL 2 distro for debugging
debugConsole=true
# Enable experimental features
[experimental]
sparseVhd=true