WSL2: How to Create a Custom Distribution for Your Development Environment

Introduction

WSL (Windows Subsystem for Linux) is a feature for running Linux distributions on Windows.
By using WSL, developers can use Linux tools and commands, enabling smooth web and backend development.

In this article, I will explain how to create a custom distribution for a development environment based on an existing distribution.
This allows you to build a unique development environment that is not affected by your existing setup.

1. WSL Distribution Management

1.1. Distributions Available in WSL

In WSL, the following Linux distributions are available:

• Ubuntu
• Debian
• Oracle Linux (Package name: OracleLinux_9_1)

These distributions are provided through the Microsoft Store.

1.2. Distributions in WSL

WSL manages the Linux environments it executes using labels called distributions.
Normally, a WSL distribution matches a Linux distribution such as Debian.

You can set a name for a WSL distribution that is different from the actual Linux distribution name.
For example, you can import the Debian distribution and give it the name dev-debian.
While the OS itself is Debian, WSL recognizes it as a distribution named dev-debian.

1.3. What is a Development Distribution?

A development distribution is a WSL distribution dedicated to a development environment created based on an existing distribution.
Since it is a completely separate environment from the original distribution, you can install various languages, development tools, and frameworks for development purposes without affecting the existing distribution.

2. Steps to Create a Development Distribution

1. Configure wsl.conf to set common behavior for each distribution.

2. Clone the development distribution from the base distribution.

3. Add development distribution settings to Windows Terminal.

4. Perform settings specific to the development distribution.

Follow the steps above to create a development distribution.

2.1. Configuring wsl.conf

In WSL, you can finely configure the behavior of a distribution by using the /etc/wsl.conf file.
By keeping the /etc/wsl.conf settings the same between the base distribution and the development distribution, you can maintain consistency in your configuration.

The settings for /etc/wsl.conf are as shown in the table below.

Section	Setting Name	Value	Application
boot	systemd	true	Starts the systemd daemon when WSL starts
network	hostname	<hostname>	Hostname of the WSL distribution
interop	appendWindowsPath	false	Does not add Windows paths after the standard paths
user	default	<username>	Username to log in as when WSL starts

By keeping these settings identical across each distribution, you can maintain configuration consistency.

How to Configure wsl.conf

Follow these steps to configure /etc/wsl.conf.

1. Create the /etc/wsl.conf file.
   Create /etc/wsl.conf with the following content. Text following # are comments.

   wsl.conf

   # Boot with systemd daemon
   [boot]
   systemd = true
   
   [network]
   # hostname changed by distribution
   hostname = <my_custom_hostname>
   
   [interop]
   # do not add Windows path
   appendWindowsPath = false
   
   [user]
   default = <defaultUserName>
   
   

   Note: Replace <my_custom_hostname> with the hostname for your development distribution, and <defaultUserName> with the login username for when WSL starts.

2. Restart WSL.
   Type wsl --shutdown in the command line to restart WSL.

   wsl --shutdown
   

From then on, WSL will start with /etc/wsl.conf applied.

2.2. Cloning the Distribution

To create a distribution, use WSL's export and import features.
After creating a tar archive of the source distribution with export, import the created tar archive into the development distribution.

How to Clone the Distribution

Follow these steps to clone a distribution.

1. Save the specified distribution as a tar archive.

   wsl --export Debian debian.tar
   

   The above command archives the source distribution into debian.tar.

2. Import the tar archive created in step 1 on the development distribution side.

   wsl --import <DevelopmentDistribution> <VirtualDiskDirectory> debian.tar
   

   Enter a development distribution name such as dev-debian for <DevelopmentDistribution>.
   For <VirtualDiskDirectory>, specify the directory where the tar archive will be extracted, such as ~/.local/share/wsl/dev-debian.

This concludes the cloning of the distribution.

2.3. Windows Terminal Settings

Add settings to Windows Terminal so that you can work on the created development distribution.

The setting procedure is as follows.

1. Open Windows Terminal and press Ctrl+, to open the settings screen.
   

2. Select [Add a new profile], then select the source profile (in this case, Debian) and duplicate it.
   

3. Change the name of the duplicated profile to the name of the development distribution.
   

4. Change the command line to switch the starting profile to the development distribution.

   wsl.exe -D <DevelopmentDistribution>
   

   For <DevelopmentDistribution>, enter the distribution name used during the distribution cloning.

5. Save the duplicated profile and close Windows Terminal.

Now you can select the development distribution from Windows Terminal.

2.4. Development Distribution Configuration

Build your development environment by installing programming languages, frameworks, etc., according to your development project.

Specifically, this includes installing necessary programming languages, libraries, frameworks, and setting up development tools. Please refer to the official websites of each language or tool for installation and setup instructions.

Conclusion

I have explained how to export a base distribution as a tar archive and create a development distribution from it.
You can create multiple development distributions from a single tar archive. By using custom distributions, you can build a clean and easy-to-use development environment specialized for each project.

Happy Hacking!

Technical Terms and Annotations

• WSL (Windows Subsystem for Linux): A feature for running Linux distributions under a Windows environment.
• wsl.conf: A file that allows fine-tuned configuration of each WSL distribution's behavior.
• systemd: A daemon that performs system initialization and service management in Linux.

References

Websites

• Advanced settings configuration in WSL: https://learn.microsoft.com/en-us/windows/wsl/wsl-config