Configuring advanced settings in WSL (2023)

  • 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).


  • 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 Windows File Explorer. The directory path should look like this:/etc/wsl.conf.


  • 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.


Per-distro configuration tuning with the wsl.conf file is only available on Windows Build 17093 and later.

(Video) 6. Advanced settings configuration in WSL

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:

(Video) Changing the Amount of CPU and Ram (WSL)

[boot] systemd = true

You 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]

activatedbooleschThis rightThis 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.
assemblyFsTabbooleschThis rightThis 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.
fuenteline/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.
optionsComma-separated list of values ​​like UID, GID, etc. See auto mount options belowempty ropeThe 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:

liquidThe user ID used for ownership of all files.The default user ID of your WSL distribution (this is 1000 by default when first installed)
GidThe group ID used for ownership of all files.The default group ID of your WSL distribution (this is 1000 by default when first installed)
maskAn octal permissions mask to exclude all files and directories000
maskAn octal delete permissions mask for all files000
maskAn octal delete permissions mask for all directories000
metadataWhether metadata is added to Windows files to support Linux system permissionsdisabled people
CairDetermines 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.


Permission masks are logically ORed before being applied to files or directories.

(Video) Windows Terminal and WSL Config Fast, Simple, and Easy Guide

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]

generate hostsbooleschThis rightThis rightsets the WSL to generate/etc/hosts. DiehostThe file contains a static mapping of host names and corresponding IP addresses.
gerarResolvConfbooleschThis rightThis rightSet WSL to generate/etc/resolv.conf. Dieresolv.confcontains a list of DNS that can resolve a given hostname to its IP address.
host namelineWindows hostnameSpecifies the hostname to use for the WSL distribution.

interop settings

Section designation:[interoperability]

These options are available in Insider Build 17713 and later.

activatedbooleschThis rightSetting this key determines whether WSL supports starting Windows processes.
anexarWindowsPathbooleschThis rightThe 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.

OriginallylineThe initial username created on the first runThe 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]

domainline""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.

(Video) Linux Apps in Windows! - WSL Setup Guide

# 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[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 service

Configuration 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.


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]

CoreFormThe kernel created by Microsoft provided the inboxAn absolute Windows path to a custom Linux kernel.
memorySize50% of total memory in Windows or 8 GB, whichever is less; for builds prior to 20175: 80% of your total RAM on WindowsHow much memory to allocate for WSL VM 2.
processorsnumberThe same number of processors in WindowsHow many processors to allocate for the WSL 2 virtual machine.
localhostReenvíobooleschThis rightBoolean indicating whether wildcard or localhost bound ports on the WSL 2 VM should be connected from the host vialocalhost:porta.
KernelCommandLinelineArchiveAdditional kernel command line arguments.
TrickSize25% of the memory size in Windows, rounded to the nearest GBHow 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 fileForm%USER PROFILE%\AppData\Local\Temp\swap.vhdxAn absolute Windows path to the virtual swap disk.
page reportbooleschThis rightPatternThis rightThis setting allows Windows to reclaim unused memory allocated to the WSL 2 virtual machine.
tabapplicationsboolesch*This rightBoolean to enable or disable support for GUI applications (WSLg) in WSL. Only available for Windows 11.
debug consoleboolesch*INCORRECTBoolean to activate an output console window that displays the content ofdmesgwhen starting a WSL 2 distribution instance. Only available for Windows 11.
nested virtualizationboolesch*This rightBoolean to enable or disable nested virtualization, allowing other nested virtual machines to run on WSL 2. Only available for Windows 11.
vmIdleTimeoutNumber*60000The 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.

(Video) Environment Settings in WSL and Windows Terminal

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\\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=true

additional resources

  • Windows Command Line Blog: Configuring WSL Automatically
  • Windows Command Line Blog: Chmod/Chown, DrvFs, File Metadata


1. WSL 2 GUI Setup and Config for Ubuntu on Windows 10
2. I Coded with WSL2 for a Week
3. How to make the ultimate Terminal Prompt on Windows 11 - This video is LONG and WORDY and DETAILED
(Scott Hanselman)
4. Customize WSL 2 - The Complete Guide To Awesomeness!
(Stefan Rows)
5. Windows development setup with WSL2, ZSH, VSCode, and more
(Christian Lempa)
6. How do I configure a WSL distro to launch in the home directory in Terminal? | One Dev Question
(Windows Developer)


Top Articles
Latest Posts
Article information

Author: Jerrold Considine

Last Updated: 22/05/2023

Views: 6013

Rating: 4.8 / 5 (58 voted)

Reviews: 89% of readers found this page helpful

Author information

Name: Jerrold Considine

Birthday: 1993-11-03

Address: Suite 447 3463 Marybelle Circles, New Marlin, AL 20765

Phone: +5816749283868

Job: Sales Executive

Hobby: Air sports, Sand art, Electronics, LARPing, Baseball, Book restoration, Puzzles

Introduction: My name is Jerrold Considine, I am a combative, cheerful, encouraging, happy, enthusiastic, funny, kind person who loves writing and wants to share my knowledge and understanding with you.