https://docs.microsoft.com/en-us/windows/wsl/wsl-config
.wslconfig
- Stored in your
%UserProfile%
directory. - Used to configure settings globally across all installed Linux distributions running as the WSL 2 version.Can be usedonly 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.
Check which version of WSL you are running.
Note
Adjusting per-distribution settings with the wsl.conf file is only available in Windows Build 17093 and later.
Configuration setting for .wslconfig
The .wslconfig file configures settings globally for all Linux distributions running with WSL 2.(For per-distribution configuration seewsl.conf).
See.wslconfigfor info on where to store the .wslconfig file.
Note
Global configuration options with.wslconfig
is only available for distributions running as WSL 2 in Windows Build 19041 and later. Keep in mind you may need to runwsl --shutdown
to shut down the WSL 2 VM and then restart your WSL instance for these changes to take affect.
This file can contain the following options that affect the VM that powers any WSL 2 distribution:
Section label:[wsl2]
key | value | default | notes |
---|---|---|---|
kernel | string | The Microsoft built kernel provided inbox | An absolute Windows path to a custom Linux kernel. |
memory | size | 50% of total memory on Windows or 8GB, whichever is less; on builds before 20175: 80% of your total memory on Windows | How much memory to assign to the WSL 2 VM. |
processors | number | The same number of processors on Windows | How many processors to assign to the WSL 2 VM. |
localhostForwarding | boolean | true | Boolean specifying if ports bound to wildcard or localhost in the WSL 2 VM should be connectable from the host via localhost:port. |
kernelCommandLine | string | Blank | Additional kernel command line arguments. |
swap | size | 25% of memory size on Windows rounded up to the nearest GB | How 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. |
swapFile | string | %USERPROFILE%/AppData/Local/Temp/swap.vhdx | An absolute Windows path to the swap virtual hard disk. |
pageReporting | boolean | true | Default true setting enables Windows to reclaim unused memory allocated to WSL 2 virtual machine. |
guiApplications | boolean* | true | Boolean to turn on or off support for GUI applications (WSLg) in WSL. Only available for Windows 11. |
debugConsole | boolean* | false | Boolean 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 | boolean* | true | Boolean to turn on or off nested virtualization, enabling other nested VMs to run inside WSL 2. Only available for Windows 11. |
vmIdleTimeout | number* | 60000 | The number of milliseconds that a VM is idle, before it is shut down. Only available for Windows 11. |
Entries with thepath
value must be Windows paths with escaped backslashes, e.g:C://Temp//myCustomKernel
Entries with thesize
value must be a size followed by a unit, for example8GB
or512MB
.
Entries with an * after the value type are only available on Windows 11.
Example .wslconfig file
The.wslconfig
sample file below demonstrates some of the configuration options available. In this example, the file path isC:/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 # 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 off default connection to bind WSL 2 localhost to Windows localhost 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