MENU
Minokamo Citizens
  1. Home
  2. education
  3. Custom Linux Distributions in WSL 2: Beyond Microsoft Store

Custom Linux Distributions in WSL 2: Beyond Microsoft Store

education

Installing Custom Linux Distributions in WSL 2: A Comprehensive Guide

WSL 2 Custom Linux Distribution Architecture Windows Host System Windows Hypervisor Platform WSL 2 Subsystem Microsoft Store Distribution Ubuntu/Debian/Fedora Pre-configured Users Limited Customization Custom Distribution Custom Linux Image Docker + GPU Support Full Control & Flexibility Windows Integration Layer Standard Components Custom Components Distributions Integration Points
table of contents

Introduction

While the Windows Subsystem for Linux (WSL) typically installs distributions from the Microsoft Store, power users often need more flexibility. This guide walks you through installing custom Linux images in WSL 2, giving you complete control over your Linux environment on Windows.

Many users encounter conflicts when running both WSL and Docker Desktop on the same system. Docker Desktop frequently reconfigures WSL settings during installation, sometimes causing unexpected changes to your WSL distribution setup. Additionally, the Microsoft Store doesn’t allow installing multiple instances of the same distribution version (though you can work around this through export/import operations).

This guide presents a practical, tested approach to installing custom Linux distributions in WSL 2, based on real-world experience rather than theoretical documentation.

Enabling WSL 2

Before installing a custom Linux distribution, you need to ensure WSL 2 is properly enabled on your Windows system:

Method 1: Quick Installation (Windows 10 version 2004 and higher or Windows 11)

Open PowerShell or Command Prompt as Administrator and run:

wsl --install

This command installs everything needed, including the Virtual Machine Platform and a default Ubuntu distribution. If you only want to enable the WSL infrastructure without installing a default distribution, use:

wsl --install --no-distribution

Method 2: Manual Installation (For older Windows versions or more control)

1.Open PowerShell or Command Prompt as Administrator

2.Enable the Windows Subsystem for Linux feature:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

3.Enable the Virtual Machine Platform feature:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

4.Restart your computer to complete the WSL installation

5.Set WSL 2 as your default version:

wsl --set-default-version 2

After completing these steps, your system is ready for installing custom Linux distributions.

Obtaining Custom Linux Images

To install a custom distribution, you’ll first need to acquire a suitable Linux image:

Official Cloud Images

Most major Linux distributions provide official cloud or container images that work well with WSL:

  1. Ubuntu: Visit Ubuntu Cloud Images for official Ubuntu images
    • Look for files with “wsl” in the name for optimized WSL experiences
    • Alternatively, use rootfs images ending with .tar.gz
  2. Debian: Visit Debian Cloud Images for official Debian images
  3. Fedora: Visit Fedora Cloud Images for official Fedora images
  4. Alpine Linux: Visit Alpine Minirootfs for lightweight Alpine images

Creating Custom Images Using Docker

You can also create your own root filesystem image using Docker:

1.Pull and run a base Linux image:

docker run --name mydistro ubuntu

2.Export the container’s filesystem as a tarball:

docker export mydistro > mydistro.tar

3.Optional: Compress the tarball to save space:

gzip mydistro.tar

Other Methods for Creating Custom Images

  1. Using an existing Linux environment: Create a minimal system and package it
  2. Using Debootstrap: Build a Debian-based system from scratch
  3. Using BusyBox: Create an ultra-minimal Linux environment
  4. Migrating from a VM: Convert VirtualBox or VMware machines to WSL
  5. Migrating an existing installation: Export a working Linux installation

Importing Custom Linux Images to WSL 2

Once you have your Linux image, you can import it into WSL:

1.Create a directory where your WSL distribution will be stored:

mkdir C:\WSL\MyCustomDistro

2.Import the image using the WSL command:

wsl --import MyCustomDistro C:\WSL\MyCustomDistro C:\path\to\rootfs.tar.gz --version 2

Where:

  • MyCustomDistro is the name you want to give your distribution
  • C:\WSL\MyCustomDistro is the location where the virtual disk will be stored
  • C:\path\to\rootfs.tar.gz is the path to your Linux image file
  • --version 2 specifies that you want to use WSL 2

3.Verify the import was successful:

wsl -l -v

4.Launch your new distribution:

wsl -d MyCustomDistro

After the import process is complete, you’ll notice a new ext4.vhdx file in the directory you specified. This virtual disk contains your Linux filesystem.

Note: When you import a custom image, you’ll be logged in as the root user by default. Unlike distributions from the Microsoft Store, custom images don’t include an initial setup wizard to create a non-root user.

User Configuration for Custom WSL Distributions

The Importance of Creating a Regular User

When using a custom WSL distribution, you’ll initially be logged in as the root user. While this might seem convenient, it presents several security and usability issues:

1. Security Concerns

  • Unrestricted System Access: Running all commands as root gives unrestricted access to system files and settings, increasing the risk of accidental system damage.
  • Potential for Destructive Commands: Without the safeguard of sudo, it’s easier to execute commands that could harm your system.
  • Security Best Practices: Most security guidelines recommend against performing routine operations with root privileges to minimize attack vectors.

2. System Stability

  • Protection Against Errors: Regular users are prevented from making system-wide changes without explicit elevation, protecting against unintended modifications.
  • Application Compatibility: Some applications refuse to run or behave differently when executed as root, assuming it’s a configuration error.

3. Environment Consistency

  • Home Directory Structure: Regular users have a properly structured home directory with default configurations.
  • Seamless Integration: Using a regular user provides a more consistent experience with standard Linux environments and other WSL distributions.

Creating a New User and Setting as Default

Follow these steps to create a regular user account and set it as the default for your WSL distribution:

1. Creating a New User

First, launch your custom WSL distribution (you’ll initially be logged in as root):

wsl -d MyCustomDistro

Create a new user with the adduser command:

adduser username

You’ll be prompted to enter a password and some optional information for the new user.

Next, grant your new user administrative privileges by adding them to the sudo group:

usermod -aG sudo username

Or, on some distributions:

gpasswd -a username sudo

2. Configure Default User with wsl.conf

WSL provides a configuration file that allows you to set the default user for your distribution. Create or edit the /etc/wsl.conf file:

nano /etc/wsl.conf

Add the following lines to specify your default user:

[user]
default=username

While you’re editing this file, you can also enable systemd support (useful for services and some applications):

[boot]
systemd=true

Save the file by pressing Ctrl+X, then Y, then Enter.

3. Restart WSL

For the changes to take effect, you need to shut down WSL completely:

From Windows PowerShell or Command Prompt:

wsl --shutdown

Or from within WSL:

shutdown now

4. Verify Configuration

After restarting your WSL distribution, verify that you’re logged in as the new user:

wsl -d MyCustomDistro
whoami

The command should return your username rather than “root”.

Alternative Methods for Setting the Default User

There are a few other ways to set the default user for WSL distributions:

Using the usermod Command (Ubuntu-specific)

For Ubuntu-based distributions:

ubuntu config --default-user username

Using the /etc/passwd File

You can also modify the user’s UID in /etc/passwd to 1000, which WSL recognizes as the default user:

sed -i 's/^username:x:[0-9]*:[0-9]*/username:x:1000:1000/' /etc/passwd

Using a Launch Command

You can create a shortcut or command that launches WSL with a specific user:

wsl -d MyCustomDistro -u username

This doesn’t change the default user but provides a convenient way to launch with a specific user.

Installing Docker and NVIDIA Container Toolkit in WSL 2

Once you have your custom WSL distribution set up with a proper user account, you may want to install Docker for container management and NVIDIA Container Toolkit for GPU acceleration. This section guides you through the process.

Installing Docker in WSL 2

Docker can be installed directly within your WSL 2 distribution, allowing you to run containers without Docker Desktop for Windows.

Method 1: Installing Docker Engine (Recommended)

1.Update your package index and install prerequisites:

sudo apt-get update

sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

2.Add Docker’s official GPG key:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

3.Set up the Docker repository:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4.Update the package index again and install Docker Engine:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

5.Verify the installation:

sudo docker run hello-world

Method 2: Using the Convenience Script

For a quicker installation:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Configuring Docker to Run Without Sudo

By default, Docker commands require root privileges, but you can configure it to run without sudo:

1.Create the docker group (if it doesn’t already exist):

sudo groupadd docker

2.Add your user to the docker group:

sudo usermod -aG docker $USER

3.Restart your WSL session for the changes to take effect:

# From Windows Command Prompt or PowerShell
wsl --shutdown

# Then restart your WSL distribution

4.Verify that you can run Docker commands without sudo:

docker run hello-world

Setting Up the Docker Daemon

In WSL 2, you’ll need to manually start the Docker daemon as it doesn’t start automatically:

1.Start the Docker service:

sudo service docker start

2.To make Docker start automatically when you launch WSL, add the following to your ~/.bashrc or ~/.zshrc:

# Start Docker daemon automatically
if service docker status 2>&1 | grep -q "is not running"; then
    wsl.exe -d "${WSL_DISTRO_NAME}" -u root -e /usr/sbin/service docker start >/dev/null 2>&1
fi

Installing NVIDIA Container Toolkit for GPU Access

If you have an NVIDIA GPU and want to use it with Docker containers in WSL 2:

Prerequisites

  1. Ensure you have the latest NVIDIA drivers installed on your Windows host.
  2. Windows 11 or Windows 10 version 21H2 or newer is recommended for best GPU support.

Installation Steps

1.Set up the NVIDIA Container Toolkit repository:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

2.Update the package index and install the NVIDIA Container Toolkit:

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

3.Configure the Docker daemon:

sudo nvidia-ctk runtime configure --runtime=docker

4.Restart the Docker daemon:

sudo systemctl restart docker

5.Verify the installation:

docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

This command should display information about your GPU, confirming that Docker containers can access it.

Troubleshooting NVIDIA Container Toolkit

If you encounter issues with GPU access in containers:

1.Check that the NVIDIA Container Toolkit is properly installed:

nvidia-container-cli --version

2.Verify that your GPU is visible to WSL 2:

nvidia-smi

3.Ensure the Docker daemon is configured to use the NVIDIA runtime:

sudo cat /etc/docker/daemon.json

4.If changes to the Docker daemon configuration are made, restart Docker:

sudo systemctl restart docker

5,For Windows-specific WSL 2 GPU issues, check the vGPU configuration:

cat /etc/wsl.conf

You may need to add GPU configuration to your .wslconfig file in Windows.

Advanced WSL Management and Optimization

Now that you have a fully configured custom WSL distribution with Docker and potentially GPU support, let’s explore some advanced techniques to manage, optimize, and troubleshoot your environment.

Backing Up and Restoring WSL Distributions

One advantage of custom WSL distributions is the ability to easily back them up and restore them when needed.

Exporting a WSL Distribution

You can export your entire WSL distribution to a tarball:

wsl --export MyCustomDistro C:\backups\MyCustomDistro-backup.tar

This creates a complete backup of your distribution that you can restore later or move to another machine.

Importing a Backup

To restore from a backup or create a duplicate distribution:

wsl --import MyRestoredDistro C:\WSL\MyRestoredDistro C:\backups\MyCustomDistro-backup.tar

This is particularly useful for:

  • Creating development/testing duplicates of your main environment
  • Transferring your setup to a new computer
  • Rolling back after major changes
  • Creating snapshots before risky operations

Optimizing WSL Performance

WSL 2 performance can be further enhanced with some tweaks:

Memory and CPU Allocation

Create or edit a .wslconfig file in your Windows user directory (C:\Users\YourUsername\.wslconfig):

[wsl2]
memory=8GB
processors=4
swap=4GB
localhostForwarding=true

Adjust these values based on your system specifications:

  • memory: Limits the memory available to WSL
  • processors: Sets the number of virtual processors
  • swap: Controls the size of the swap file
  • localhostForwarding: Improves network performance between Windows and WSL

Disk I/O Performance

For optimal disk performance:

  1. Place your WSL distribution on an SSD rather than an HDD
  2. Avoid storing your distribution in synced folders (like OneDrive)
  3. Use the Linux filesystem for development work rather than Windows-mounted drives

File System Integration

WSL provides two ways to access files across systems:

  1. Access Windows files from WSL:
    • Windows drives are mounted at /mnt/c, /mnt/d, etc.
    • Consider the performance impact when working with files on Windows drives
  2. Access WSL files from Windows:
    • Use the \\wsl$\DistributionName\ path in File Explorer
    • Use the wsl.exe -d DistributionName cat /path/to/file command

Troubleshooting Common Issues

WSL Won’t Start

If your WSL distribution won’t start:

  1. Check the status with wsl --list --verbose
  2. Try restarting with wsl --shutdown followed by starting your distribution
  3. Check for Windows updates or WSL updates
  4. If necessary, reset WSL with wsl --unregister DistributionName (warning: this deletes the distribution)

Network Connectivity Issues

For network problems:

  1. Check your WSL network adapter with ip addr
  2. Ensure Windows Firewall isn’t blocking WSL connections
  3. Restart the WSL network service with:
    sudo service network-manager restart

Display and GUI Application Issues

For running GUI applications from WSL:

  1. Install an X server on Windows (like VcXsrv or Xming)
  2. Set the DISPLAY environment variable in WSL:
    export DISPLAY=:0
  3. For WSLg (built-in GUI support on newer Windows):
    • Ensure you’re running Windows 11 or Windows 10 with the latest updates
    • WSLg should work automatically with no additional configuration

Advanced WSL Features

Using Systemd

Starting with WSL version 0.67.6 and later, systemd is supported:

  1. Enable systemd by adding to /etc/wsl.conf:
    [boot]
    systemd=true
  2. Restart WSL with wsl --shutdown

This enables running services like MySQL, PostgreSQL, and others that depend on systemd.

WSL Remote Development

WSL integrates well with development tools:

  1. VS Code Remote WSL: Develop in WSL while using VS Code on Windows
    • Install the “Remote – WSL” extension in VS Code
    • Use the “Remote-WSL: New Window” command to connect
  2. JetBrains IDEs: Use the WSL integration feature
    • Configure a “WSL” toolchain in your project settings
    • Run and debug directly from the IDE

Conclusion

Setting up a custom WSL 2 distribution with Docker and potentially GPU support gives you tremendous flexibility for development, testing, and running Linux workloads on Windows. By following the steps in this guide, you have:

  1. Enabled WSL 2 on your Windows system
  2. Obtained and imported a custom Linux distribution
  3. Created a proper user account for security and usability
  4. Installed and configured Docker for container management
  5. Set up NVIDIA Container Toolkit for GPU acceleration (if applicable)
  6. Learned advanced management and optimization techniques

This approach solves common issues like distribution conflicts between WSL and Docker Desktop, while providing you with a tailored Linux environment that meets your specific needs.

Remember that WSL is continuously evolving, with Microsoft regularly adding new features and improvements. Keep your system updated to benefit from these enhancements, and check the official WSL documentation for the latest information.

Frequently Asked Questions

Can I run multiple WSL distributions simultaneously?

Yes, you can run multiple WSL distributions simultaneously. Each distribution operates independently with its own filesystem, processes, and configuration.

How do I access my Windows files from WSL?

Windows drives are automatically mounted under /mnt/ in WSL. For example, your C: drive is accessible at /mnt/c/.

How do I access my WSL files from Windows?

You can access WSL files using the \\wsl$\DistributionName\ path in File Explorer or by using the explorer.exe . command from within your WSL terminal.

Can I use WSL for production workloads?

While WSL 2 is very capable, it’s primarily designed for development and testing. For production workloads, dedicated Linux servers or containers orchestrated with Kubernetes are typically recommended.

Does WSL support USB devices?

USB device support in WSL is limited. Some devices might work through USB/IP, but for full hardware access, a traditional virtual machine or dual-boot setup might be more appropriate.

How do I update my WSL Linux distribution?

Update your distribution using the standard package management commands for your distribution:

For Alpine: apk update && apk upgrade

For Ubuntu/Debian: sudo apt update && sudo apt upgrade

For Fedora: sudo dnf upgrade

education

If you like this article, please
Follow !

Please share if you like it!
table of contents