- Article
- 12 minutes to read
Diewsl.confmi.wslconfigThe files are used to set advanced configuration options per distribution (wsl.conf) and globally across all WSL 2 distributions (.wslconfig). This guide covers all configuration options, when to use each file type, where to save the file, configuration file examples, and tips.
What is the difference between wsl.conf and .wslconfig?
You can configure settings for your installed Linux distributions that are automatically applied each time WSL is started in two ways using:
- .wslconfigto configure the settingsglobalon all installed distributions running on WSL 2.
- wsl.confto configure the settingsby distributionfor Linux distributions running on WSL 1 or WSL 2.
Both file types are used to configure WSL tweaks, but the location of the file, the length of the tweak, and the version of WSL your distribution is running on all affect which file type you should choose.
The version of WSL you are running affects your configuration settings. WSL 2 runs as a lightweight virtual machine (VM) and therefore uses virtualization settings that allow you to control the amount of memory or processors used (which you can learn if you use Hyper-V or VirtualBox).
wsl.conf
- saved in
/etcDistribution directory as Unix file. - It is used to configure the settings per distribution. The settings defined in this file only apply to the specific Linux distribution that contains the directory where this file is stored.
- It can be used for distributions running on either version, WSL 1 or WSL 2.
- get there
/etcdirectory for an installed distribution, use the distribution's command line withCD /to access the root directorylslist files orexplorer.exe.in Windows File Explorer. The directory path should look like this:/etc/wsl.conf.
.wslconfig
- saved in your
%user profile%Directory. - It is used to configure settings globally for all installed Linux distributions running as WSL version 2.
- It can be usedonly for distributions running WSL 2. Distributions running as WSL 1 are not affected by this setting, as they are not running as a virtual machine.
- to get to you
%user profile%Directory, use in PowerShellcompact discto access your home directory (which is usually your user profile,C:\Users\<username>) or you can open Windows File Explorer and type%user profile%in the address bar. The directory path should look like this:C:\Users\<username>\.wslconfig.
WSL detects the presence of these files, reads the content, and automatically applies configuration options when you start WSL. If the file is missing or corrupted (incorrect markup format), WSL will still start normally without applying the configuration settings.
Check which version of WSL you are running.
Use
Per-distro configuration tuning with the wsl.conf file is only available on Windows Build 17093 and later.
The 8 second rule
You must wait for the subsystem your Linux distribution is running on to completely shut down and reboot for configuration settings updates to appear. This usually takes about 8 seconds after ALL instances of the distribution shell have been closed.
If you start a distribution (eg Ubuntu), change the configuration file, close the distribution and start again. You can assume that your configuration changes took effect immediately. This is not currently the case as the subsystem may still be running. You must wait for the subsystem to complete before restarting it to allow enough time for the changes to take effect. You can check if your Linux distribution (shell) is still running after closing it using PowerShell with the command:wsl --list --running. If no distribution is running, you will get the response: "No distribution is running." You can now restart the deployment to see how the configuration updates are applied.
The commandwsl - turn offit's a quick way to restart WSL 2 distributions, but it will shut down all running distributions, so use it wisely.
Configuration settings for wsl.conf
The wsl.conf file defines the configuration per distribution.(For global configuration of WSL 2 distributions, see.wslconfig).
The wsl.conf file supports four sections:auto mount,red,interoperability, miof the user.(Following .ini file conventions, keys are declared in a section, like .gitconfig files.)verwsl.conffor information on where to save the wsl.conf file.
support system
Many Linux distributions run "systemd" by default (including Ubuntu), and WSL has recently added support for this system/service manager, making WSL even more like running your favorite Linux distributions on a full machine. . You need WSL version 0.67.6+ to enable systemd. Check your WSL version with the commandwsl --version. If you need to update, you canlatest version of WSL in Microsoft Store. Learn more atblog ad.
To enable systemd, open yourwsl.conffile in a text editor withsudoto get admin permissions and add these lines to the/etc/wsl.conf:
[boot] systemd = trueYou should also close your WSL distributionwsl.exe --shutdownPowerShell to restart your WSL instances. Once your distribution has rebooted, systemd should be running. You can confirm with the command:systemctl list-unit-files --type=servicio, which shows the status of your services.
auto mount setup
Section designation:[auto mount]
| wrench | Wert | Originally | Comments |
|---|---|---|---|
| activated | boolesch | This right | This rightcauses fixed triggers (i.e.,C:/oD:/) to auto-mount with DrvFs on/mnt.INCORRECTmeans the drives are not mounted automatically, but you can still mount them manually or viafstab. |
| assemblyFsTab | boolesch | This right | This rightput/etc/fstabprocessed at WSL startup. /etc/fstab is a file where you can declare other file systems as an SMB share. So you can automatically mount these filesystems to WSL at startup. |
| fuente | line | /mnt/ | Specifies the directory where hard drives are automatically mounted. This is set by default./mnt/, so the Windows file system is mounted on drive C/mnt/c/. when you change/mnt/for/windir/, you need to wait for your permanently installed C drive to appear/windir/c. |
| options | Comma-separated list of values like UID, GID, etc. See auto mount options below | empty rope | The automount option values are listed below and are appended to the DrvFs default mount option string.Only DrvFs-specific options can be specified. |
Automount options are applied as mount options to all automounted drives. To change options for only a specific unit, use the/etc/fstabfile instead. Options that the assembly binary would normally parse in a prompt are not supported. If you want to explicitly specify these options, you must include each unit for which you want to do this/etc/fstab.
Auto mount options
Setting different mount options for Windows drives (DrvFs) can control how file permissions are calculated for Windows files. The following options are available:
| As | Description | Pattern |
|---|---|---|
| liquid | The user ID used for ownership of all files. | The default user ID of your WSL distribution (this is 1000 by default when first installed) |
| Gid | The group ID used for ownership of all files. | The default group ID of your WSL distribution (this is 1000 by default when first installed) |
| mask | An octal permissions mask to exclude all files and directories | 000 |
| mask | An octal delete permissions mask for all files | 000 |
| mask | An octal delete permissions mask for all directories | 000 |
| metadata | Whether metadata is added to Windows files to support Linux system permissions | disabled people |
| Cair | Determines if directories are case sensitive and if new directories created with WSL have the flag set. To seebig and small lettersfor a detailed explanation of the options. Options includethe end,directory, oforce. | the end |
By default, WSL sets the UID and GID to the default user value. For example, on Ubuntu, the default user is uid=1000, gid=1000. If this value is used to specify an option other than gid or uid, the default user value will be overridden. Otherwise, the default value is always added.
The user file creation mode mask (umask) sets the permission for newly created files. The default is 022, only you can write data, but everyone can read data. The values can change to reflect different permission settings. For example,umask=077change the permission to fully private, no other user can read or write data. To specify more permissions, fmask (files) and dmask (directories) can also be used.
Use
Permission masks are logically ORed before being applied to files or directories.
What is DrvFs?
DrvFs is a file system plugin for WSL designed to support interoperability between WSL and the Windows file system. DrvFs allows WSL to mount drives with compatible file systems to /mnt, eg /mnt/c, /mnt/d, etc.big and small lettersPage.
network settings
Section designation:[Red]
| wrench | Wert | Originally | Comments |
|---|---|---|---|
| generate hosts | boolesch | This right | This rightsets the WSL to generate/etc/hosts. DiehostThe file contains a static mapping of host names and corresponding IP addresses. |
| gerarResolvConf | boolesch | This right | This rightSet WSL to generate/etc/resolv.conf. Dieresolv.confcontains a list of DNS that can resolve a given hostname to its IP address. |
| host name | line | Windows hostname | Specifies the hostname to use for the WSL distribution. |
interop settings
Section designation:[interoperability]
These options are available in Insider Build 17713 and later.
| wrench | Wert | Originally | Comments |
|---|---|---|---|
| activated | boolesch | This right | Setting this key determines whether WSL supports starting Windows processes. |
| anexarWindowsPath | boolesch | This right | The setting of this key determines whether WSL adds Windows path elements to the $PATH environment variable. |
User settings
Section designation:[From the user]
These options are available in build 18980 and later.
| wrench | Wert | Originally | Comments |
|---|---|---|---|
| Originally | line | The initial username created on the first run | The setting for this key specifies which user will run when a WSL session is first started. |
startup settings
Startup Configuration is only available on Windows 11 and Server 2022.
Section designation:[Stiefel]
| wrench | Wert | Originally | Comments |
|---|---|---|---|
| domain | line | "" | A string of command that you want to run when the WSL instance starts. This command is run as root user. for example.:Start Docker Service. |
example wsl.conf file
Diewsl.confThe following sample file shows some of the available configuration options. In this example, the distribution is Ubuntu-20.04 and the file path is\\wsl.localhost\Ubuntu-20.04\etc\wsl.conf.
# Automount Windows drive when distribution starts [automount] # Setting this to true will automatically mount fixed drives (C:/ or D:/) with DrvFs in the root directory specified above. Setting to "false" means that drives are not automounted, but must be mounted manually or with fstab.enabled = true# Sets the directory where fixed drives are automounted. This example changes the mount location so that your C drive is /c and not the default /mnt/c. root = /# DrvFs-specific options can be specified. options = "metadata,uid=1003,gid=1003,umask=077,fmask=11,case=off"# Specifies the `/etc/fstab` file to process when starting a WSL distribution .mountFsTab = true# host of networks that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, which prevents WSL from performing the default behavior of automatically generating /etc/hosts, and sets generateResolvConf to false, which prevents automatic generation. WSL excludes /etc/resolv.conf so you can create your own (for example, nameserver 1.1.1.1).[network]hostname=DemoHostgenerateHosts=falsegenerateResolvConf=false# Set whether WSL interop processes support starting Windows applications and adding path variables. Setting this to false prevents Windows processes from starting and blocks the addition of $PATH environment variables. [interop]enabled = falseappendWindowsPath = false# Sets the user when starting a distribution with WSL. [user] default = DemoUser# Specifies a command to run when a new instance of WSL is started. This example starts the Docker container service. [boot]command = start docker serviceConfiguration definition for .wslconfig
The .wslconfig file defines settings globally for all Linux distributions running WSL 2.(For configuration by distribution, seewsl.conf).
ver.wslconfigfor information on where to save the .wslconfig file.
Use
Global configuration options with.wslconfigit is only available for distributions running as WSL 2 on Windows Build 19041 and later. Please note that you may have to walkwsl - turn offto shut down the WSL 2 virtual machine and restart your WSL instance for these changes to take effect.
This file can contain the following options that affect the virtual machine that powers each WSL 2 distribution:
Section designation:[wsl2]
| wrench | Wert | Originally | Comments |
|---|---|---|---|
| Core | Form | The kernel created by Microsoft provided the inbox | An absolute Windows path to a custom Linux kernel. |
| memory | Size | 50% of total memory in Windows or 8 GB, whichever is less; for builds prior to 20175: 80% of your total RAM on Windows | How much memory to allocate for WSL VM 2. |
| processors | number | The same number of processors in Windows | How many processors to allocate for the WSL 2 virtual machine. |
| localhostReenvío | boolesch | This right | Boolean indicating whether wildcard or localhost bound ports on the WSL 2 VM should be connected from the host vialocalhost:porta. |
| KernelCommandLine | line | Archive | Additional kernel command line arguments. |
| Trick | Size | 25% of the memory size in Windows, rounded to the nearest GB | How much swap space to add to the WSL 2.0 virtual machine for non-swap files. Swap space is disk-based RAM that is used when memory requirements exceed the limit of the hardware device. |
| paging file | Form | %USER PROFILE%\AppData\Local\Temp\swap.vhdx | An absolute Windows path to the virtual swap disk. |
| page report | boolesch | This right | PatternThis rightThis setting allows Windows to reclaim unused memory allocated to the WSL 2 virtual machine. |
| tabapplications | boolesch* | This right | Boolean to enable or disable support for GUI applications (WSLg) in WSL. Only available for Windows 11. |
| debug console | boolesch* | INCORRECT | Boolean to activate an output console window that displays the content ofdmesgwhen starting a WSL 2 distribution instance. Only available for Windows 11. |
| nested virtualization | boolesch* | This right | Boolean to enable or disable nested virtualization, allowing other nested virtual machines to run on WSL 2. Only available for Windows 11. |
| vmIdleTimeout | Number* | 60000 | The number of milliseconds a VM is idle before shutting down. Only available for Windows 11. |
tickets withFormThe value should be Windows paths with escaped backslashes, for example, for example:C:\\Temp\\myCustomKernel
tickets withSizeFor example, the value should be a quantity followed by a unit.8GBo512 megabytes.
Entries with a * after the value type are only available on Windows 11.
Example .wslconfig file
Die.wslconfigThe following sample file shows some of the available configuration options. In this example, the file path isC:\Users\<username>\.wslconfig.
# The setting applies to all Linux distributions running on WSL 2[wsl2]. # Limit the memory of the VM to use no more than 4 GB. This can be set to an integer with GB or MBmemory=4GB. # Configure the virtual machine to use two processors virtualprocessors=2 # Specify a custom Linux kernel to use with your installed distributions. The default kernel used can be found at https://github.com/microsoft/WSL2-Linux-Kernelkernel=C:\\temp\\myCustomKernel# Set additional kernel parameters and in this case launch more Linux base images old like Centos 6kernelCommandLine = vsyscall= emulate# Set swap size to 8 GB, default is 25% of available RAM.swap=8 GB# Set swap file path location, value default is %USERPROFILE%\ AppData\Local\Temp\swap.vhdxswapfile= C:\ \ temp \\wsl-swap.vhdx# Turn off page reporting so that WSL keeps all allocated memory consumed by Windows and returns nothing when freepageReporting=false # Disable default connection to bind WSL 2 localhost to Windows localhostlocalhostforwarding=true# Disable nested virtualization nestedVirtualization= false# Enable console output showing dmesg content when opening a dis WSL 2 distribution for debuggingConsole=trueadditional resources
- Windows Command Line Blog: Configuring WSL Automatically
- Windows Command Line Blog: Chmod/Chown, DrvFs, File Metadata