WSL instance configuration¶
You can configure instances of Ubuntu on WSL using different methods.
Each configuration method has a different scope and use-case. Depending on the method, you may affect all Ubuntu instances or only one Ubuntu instance.
Method |
Scope |
Location |
|---|---|---|
General settings that apply to all WSL instances |
Graphical application named |
|
General settings that apply to all WSL instances |
|
|
Settings for a specific WSL instance only |
|
|
Ubuntu provisioning settings for instances of a named distribution |
|
|
Pro settings that apply to all compatible Ubuntu instances |
Installable graphical application |
WSL Settings¶
WSL Settings is a graphical application that comes with WSL, allowing you to manage general settings that apply to all WSL 2 instances. It is analogous to the .wslconfig file.
The WSL Settings application can be used for configurations including hardware resource limits, networking, and custom kernels.
For changes to apply, you may need to run wsl --shutdown from PowerShell to shut down the WSL 2 VM and then restart your WSL instance.
.wslconfig¶
Global configuration settings that apply to all WSL 2 instances can be managed using the .wslconfig file located at %UserProfile%\.wslconfig. By default, .wslconfig does not exist, and it may need to be created manually.
The .wslconfig file is analogous to the graphical application WSL Settings. When possible, it is recommended to use WSL settings instead of directly modifying .wslconfig as it is simpler to use and more robust.
For changes to apply, you may need to run wsl --shutdown from PowerShell to shut down the WSL 2 VM and then restart your WSL instance.
wsl.config¶
Each unique instance can be configured using the wsl.config file located at /etc/wsl.config within a given WSL instance. Settings stored in this file are only applied to that instance.
To modify this file, enter the target WSL instance, and then open /etc/wsl.config in a text editor of your choice with admin permissions using sudo. For example, sudo nano /etc/wsl.config.
The wsl.config file can be used to configure instance-specific settings such as systemd support, automount settings, network settings, interoperability settings, and user settings.
Warning
Certain settings in .wslconfig are incompatible with specific Ubuntu features. For example, we generally recommend keeping systemd and interoperability enabled.
For additional information on how features like systemd and interoperability affect the functionality of Ubuntu on WSL, please see the explanation page comparing WSL versions.
To apply changes made to a wsl.config file, you need to restart your WSL instances by running wsl --shutdown or wsl --terminate <Instance Name> from PowerShell. Confirm that the instance is no longer running with wsl --list --running.
Cloud-init¶
Cloud-init can be used to automatically set up instances of Ubuntu on WSL. With cloud-init, you can pre-configure instances of a named Ubuntu distribution, such as by creating users, pre-installing software, or running arbitrary commands on initial startup.
Important
Cloud-init is only available when systemd and interoperability is enabled. For additional information, please reference the explanation page on how WSL versions affect Ubuntu.
To use cloud-init, place your cloud-init files in %UserProfile%\.cloud-init\ (create this folder if it does not exist), and name your cloud-init file <Distro Name>.user-data, replacing <Distro Name> with the name of the distribution that you want to configure.
Note
Cloud-init is only applied once, during the first startup of a WSL instance. Subsequent edits to the .user-data file will have no effect unless forcibly applied.
Finally, install that distribution as you would normally, and the cloud-init configuration should apply automatically.
Ubuntu Pro for WSL¶
Ubuntu Pro for WSL (UP4W) is a graphical application that automatically configures all compatible instances of Ubuntu on WSL to attach to your Ubuntu Pro subscription.