Complete wsl.conf Reference and Template¶
Since I started using WSL as my primary environment for learning and development, I began collecting the settings of its configuration files. By gradually testing and verifying the behavior of each setting and its dependencies, I compiled a documented and ready-to-use wsl.conf template, which I apply across all of my instances.
This template covers all the settings known to me, including:
- descriptions
- WSL version for which setting is available
- dependencies
- possible values
- default values
Each parameter is explicitly defined and has a default value, except for a few individual settings that do not.
boot.commandnetwork.hostnameuser.default
wsl.conf template¶
# WSL per-instance configuration file wsl.conf
# Location: /etc/wsl.conf
[boot]
# Enables systemd support
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
systemd = true
# Prevents creation of systemd units when systemd is enabled
# Available in: WSL 2
# Dependencies: boot.systemd = true
# Default: true
# Values:
# - true
# - false
protectBinfmt = true
# Command to run at each boot (as root)
# Available in: WSL 2
# Dependencies: Only a single command is allowed, without shell pipes,
# redirection, or script
# Default: Not set
# Example: command = "service docker start"
# command =
[automount]
# Automatically mounts Windows drives under the specified mount root
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
enabled = true
# Sets the CGroup version for filesystem mounts
# Available in: WSL 2
# Dependencies: None
# Default: v2
# Values:
# - v1
# - v2
cgroups = v2
# Automatic configuration /etc/ld.so.conf.d/ld.wsl.conf generation
# Available in: WSL 2
# Dependencies: automount.enabled = true
# Default: true
# Values:
# - true
# - false
ldconfig = true
# Mounts entries from /etc/fstab at boot
# Available in: WSL 1/2
# Dependencies: automount.enabled = true
# Default: true
# Values:
# - true
# - false
mountFsTab = true
# Sets the mount point for Windows mounted drives
# Available in: WSL 1/2
# Dependencies: automount.enabled = true
# Default: /mnt/
# Values: Any valid absolute directory path
root = /mnt/
# Sets additional mounting options as a comma-separated list
# Available in: WSL 1/2
# Dependencies: automount.enabled=true
# Default:
# - options = "uid=1000,gid=1000,umask=022,dmask=000,fmask=000,case=off"
#
# metadata: Enables storing and applying Linux file permissions
# on mounted drives
# Default: disabled
# Values:
# - metadata: enabled
# - not set: disabled
#
# uid: User ID assigned as the owner of all files
# Default: 1000
# Values: Positive integer
#
# gid: Group ID assigned as the group owner of all files
# Default: 1000
# Values: Positive integer
#
# umask: Octal mask specifying which permission bits to remove from
# default permissions when creating files and directories
# Dependencies:
# - metadata is enabled
# Default: 022
#
# dmask: Octal mask specifying which permission bits to remove from
# default permissions when creating directories
# Dependencies:
# - metadata is enabled
# - Overrides umask for directories
# Default: 000
#
# fmask: Octal mask specifying which permission bits to remove from
# default permissions when creating files
# Dependencies:
# - metadata is enabled
# - Overrides umask for files
# Default: 000
#
# case: Controls case sensitivity for mounted directories and whether
# new directories created under WSL have case sensitivity enabled
# Default: off
# Values:
# - off: Case sensitivity disabled
# - dir: Enables case sensitivity for directories
# - force: Forces case sensitivity for directories
#
# Example:
# - options = "metadata,uid=1000,gid=1000,umask=022,dmask=022,fmask=133,case=off"
options = "uid=1000,gid=1000,umask=022,dmask=000,fmask=000,case=off"
[network]
# Sets a custom hostname
# Available in: WSL 1/2
# Dependencies: None
# Default: Windows hostname
# Value: Any valid hostname
# hostname =
# Automatically creates /etc/hosts on each launch
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
generateHosts = true
# Automatically creates /etc/resolv.conf on each launch
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
generateResolvConf = true
[gpu]
# Enables access to the Windows GPU via para-virtualization
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
enabled = true
# Appends GPU driver paths
# Available in: WSL 2
# Dependencies: gpu.enabled = true
# Default: true
# Values:
# - true
# - false
appendLibPath = true
[time]
# Synchronizes Linux timezone with the Windows host
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
useWindowsTimezone = true
[interop]
# Allows launching Windows executables from the Linux environment
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
enabled = true
# Appends Windows system paths to the Linux $PATH variable
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
appendWindowsPath = true
[user]
# Specifies the default user to be used when launching the distribution
# Available in: WSL 1/2
# Dependencies: User must already exist in the Linux system
# Default: Windows username
# default =