Conventions¶
This section explains terminology, notation, and examples used throughout the site.
General terms¶
Distribution¶
A distribution is an archive containing the rootfs of the operating system being installed. Most installable distributions use the .wsl extension.
Instance¶
An instance is a system installed from a distribution, ready to run or already running.
cloud-init¶
cloud-init is a system designed to automatically configure a Linux distribution during its first boot.
Configuration terms¶
Configuration format¶
Main configurations¶
Description
- Configuration files use the INI format, where settings are grouped into sections.
- Each section name in the configuration file is specified only once.
- The order of sections and the order of settings within sections does not matter.
Info
- All configuration examples explicitly specify the section each setting belongs to. This means the setting must be placed in that section.
- The current order of sections and settings in configurations is chosen for logical grouping.
Section name¶
A section in a configuration file is a logically separated block of settings grouped by a specific topic or functionality.
In this setting example, the section title is highlighted.
[boot]
# Enables systemd support
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
systemd = true
Setting name¶
A setting is a configurable parameter that controls WSL, a distribution, or instance behavior.
In this example, the setting is highlighted.
[boot]
# Enables systemd support
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
systemd = true
Fully qualified setting name¶
section.setting is a fully qualified setting name used to reference a configuration option located in a specific section of a configuration file. In documentation or articles, may encounter examples like boot.systemd or boot.systemd = true, which use the fully qualified setting name to unambiguously indicate where the setting resides
In this example, both the section and the setting are highlighted:
[boot]
# Enables systemd support
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
systemd = true
Setting value¶
A setting value is the data assigned to a setting that determines how the corresponding configuration option will work. A value can be a string, a number, a Boolean flag, or another data type allowed by the configuration file format. The numeric value can be negative, positive, or zero.
In this example, the setting that has a Boolean value is highlighted:
[boot]
# Enables systemd support
# Available in: WSL 2
# Dependencies: None
# Default: true
# Values:
# - true
# - false
systemd = true
In this example, the setting that has an integer value is highlighted:
[wsl2]
# Duration before shutting down the WSL virtual machine when idle
# Dependencies: None
# Default: 60000 (60 seconds)
# Values:
# - -1: Never shut down automatically
# - 0: Shut down immediately after all WSL instances have exited
# - Positive integer: Shut down after the specified idle time (in milliseconds)
vmIdleTimeout = 60000
In this example, the setting that has a string value is highlighted:
# - false
hardwarePerformanceCounters = true
[experimental]
# Defines memory reclaim strategy after detecting idle CPU inactivity
# Dependencies: None
# Default: gradual
# Values:
# - disabled: Disable memory reclaim
Experimental settings¶
An experimental setting is a configuration option that enables features still under development or testing. Experimental settings are typically disabled by default and should be used with caution.
Info
The [experimental] section is available only in the .wslconfig configuration file.
In this example setting, the [experimental] section is highlighted: