Skip to content

wsl.conf

A per-instance configuration file used by both WSL 1 and WSL 2 instances, which controls parameters for a specific instance.

Overview

  • Local per-instance configuration file.
  • By default, may contain one or two settings: boot.systemd and user.default.
  • Settings apply to instances running under both WSL 1 and WSL 2.
  • Some settings are available only for WSL 2.
  • Located at /etc/wsl.conf.
  • Uses the INI format, with settings grouped into sections.
  • Uses the INI format, with settings grouped into sections.
  • Availability of parameters depends on the WSL version and release.
  • Changes take effect only after restarting the instance using wsl --terminate <InstanceName>.

Settings

boot

The settings described below are located in the [boot] section.

systemd

# Enables systemd support
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
systemd = true

protectBinfmt

# 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

# 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"

automount

The settings described below are located in the [automount] section.

enabled

# Automatically mounts Windows drives under the specified mount root
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false

cgroups

# Sets the CGroup version for filesystem mounts
# Available in: WSL 2
# Dependencies: None
# Default: v2
# Values:
# - v1
# - v2

ldconfig

# Automatic configuration /etc/ld.so.conf.d/ld.wsl.conf generation
# Available in: WSL 2
# Dependencies: automount.enabled = true
# Default: true
# Values:
# - true
# - false

mountFsTab

# Mounts entries from /etc/fstab at boot
# Available in: WSL 1/2
# Dependencies: automount.enabled = true
# Default: true
# Values:
# - true
# - false

root

# 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

options

# 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

The settings described below are located in the [network] section.

hostname

# Sets a custom hostname
# Available in: WSL 1/2
# Dependencies: None
# Default: Windows hostname
# Value: Any valid hostname
# hostname =

generateHosts

# Automatically creates /etc/hosts on each launch
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
generateHosts = true

generateResolvConf

# Automatically creates /etc/resolv.conf on each launch
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
generateResolvConf = true

gpu

The settings described below are located in the [gpu] section.

enabled

# Enables access to the Windows GPU via para-virtualization
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
enabled = true

appendLibPath

# Appends GPU driver paths
# Available in: WSL 2
# Dependencies: gpu.enabled = true
# Default: true
# Values:
# - true
# - false
appendLibPath = true

time

The settings described below are located in the [time] section.

useWindowsTimezone

# Synchronizes Linux timezone with the Windows host
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
useWindowsTimezone = true

interop

The settings described below are located in the [interop] section.

enabled

# Allows launching Windows executables from the Linux environment
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
enabled = true

appendWindowsPath

# Appends Windows system paths to the Linux $PATH variable
# Available in: WSL 1/2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
appendWindowsPath = true

user

The settings described below are located in the [user] section.

default

# 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 =

Full configuration

This is the fully documented per-instance configuration file reference and 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 =