Installing Linux on Windows using WSL 2

Introduction

The Linux Containers in Docker Desktop generally follow this architecture:

1. Moby VM: Linux Containers are built within the Linux Container Host created by the Moby VM. For full details, please refer to Linux containers on Windows 10.
2. LCOW: An experimental architecture proposed by Docker Desktop that allows both Windows and Linux Containers to run simultaneously. You can refer to this article to understand the architectural differences between the two.
3. WSL 2: An abbreviation for Windows Subsystem for Linux 2, a subsystem provided by Microsoft that contains a full Linux kernel under Windows, allowing you to operate Linux files directly in Windows using File Explorer or the Command Line.

Version Requirements for Installing WSL 2 on Windows

• Windows 10 must be version 2004 (Build 19041) or higher.
• Windows 11.

Installing WSL 2

• The following commands should be entered in Windows PowerShell (as Administrator).
• Where you see <DistributionName>, replace it with the Linux package you wish to install.

1. Install WSL 2.

   wsl --install
   # or
   wsl --install -d <DistributionName>

TIP

• If no Linux distribution is specified, Ubuntu is used by default.
  • You can only omit the distribution name if no Linux distributions have been installed yet.
  • You can use wsl --list --online or wsl -l -o to query the names of available Linux distributions.

1. Set WSL 2 as the default version.

   wsl --set-default-version 2

2. Set the WSL version of the newly installed Linux distribution to 2.

   wsl --set-version <DistributionName> 2

3. Set the default Linux distribution.

   wsl --set-default <DistributionName>
   # or
   wsl -s <DistributionName>

TIP

• You can use wsl --list --verbose or wsl -l -v to query which distributions are currently installed and in use.

  • When installing Docker Desktop, if you check "Install required components for WSL 2", the following two Linux distributions will be installed:

    • docker-desktop: Used to run the Docker Engine (dockerd).
    • docker-desktop-data: Used to store Containers and Images.

1. Remove a Linux distribution.

   wsl --unregister <DistributionName>

WARNING

Please note that removing a Linux distribution will delete its corresponding folder and all data, and this action cannot be undone.

Official Documentation

• Install Linux on Windows with WSL
• Basic commands for WSL

Integrating Linux Containers with WSL 2

Docker officially mentions the following advantages of integrating Linux Containers with WSL 2:

1. Docker Desktop uses the dynamic memory allocation feature in WSL 2, which significantly improves resource consumption.
2. With WSL 2, the time required to start the Docker daemon after a cold boot is significantly faster.

To integrate WSL 2 in Linux Containers mode, configure the following:

• [x] Settings > General > Use the WSL 2 based engine.
• [x] Settings > Resources > WSL Integration:
  • [x] Enable integration with my default WSL distro.
  • [x] Enable the Linux package you want to use under "Enable integration with additional distros:".

Official Documentation

Docker Desktop WSL 2 backendGet started with Docker remote containers on WSL 2

Running Windows Containers and Linux Containers Simultaneously

Docker Desktop has two modes: Windows Containers and Linux Containers, but only one can run at a time. In the past, the experimental Linux Container On Windows (LCOW) was released in v17.09, which allowed Docker to run Linux Containers using Hyper-V Containers while in Windows Containers mode; however, this experimental feature has been deprecated.

Now, with WSL 2, you can run both Windows and Linux systems on your computer simultaneously. Therefore, you can switch Docker Desktop to Windows Containers mode and install the Docker Engine on Linux to run Linux Containers.

Currently, when switching to Windows Containers for the first time in a Docker version, you need to execute the following command. For related discussions, please refer to this Question:

Enable-WindowsOptionalFeature -Online -FeatureName $("Microsoft-Hyper-V", "Containers") -All

If you encounter the following error message when running docker-compose up, please refer to this article for a solution.

docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post http://%2Fvar%2Frun%2Fdocker.sock/v1.26/containers/create: dial unix /var/run/docker.sock: connect: permission denied. See 'docker run --help'.

Current versions of Ubuntu come with the Docker Engine pre-installed. If you find the default version too old after installing WSL 2 Ubuntu, you can refer to the official article to update the Docker Engine version.

Methods for Mutual Access Between Windows and Linux Distributions

• Windows can access the root directory of a Linux distribution by entering \\wsl$\<DistributionName> in the File Explorer address bar, where <DistributionName> is the name of the distribution to connect to. Accessing Linux files via \\wsl$ will use the default user of the WSL distribution.
• Linux connects to the root directory of each drive via the path /mnt/<WindowsDriveLetter>, where <WindowsDriveLetter> is the drive letter to connect to. When a Linux distribution accesses Windows files, file permissions are calculated from Windows permissions or read from metadata added to the files by Linux.

For detailed content, please refer to

• Working across Windows and Linux file systems
• File permissions for WSL

Unresolved Issues

1. When switching to Windows Container mode, Docker inside WSL 2 does not start automatically upon reboot.
2. Some online resources suggest installing WSL 2 using the old manual installation steps mentioned in "Manual installation steps for older versions of WSL". According to this article, this may cause Windows "File Explorer" to be unable to modify files on Linux via "Network Neighborhood". However, after installing using the new method, I found that files outside the user folder (/home/{username}/) still have this issue after a reboot. Therefore, for those not accustomed to the Linux interface, it may be worth evaluating whether to centralize data storage within the user folder.

The above issues might be solvable via Advanced configuration settings in WSL, but I have not tested this personally.

Regarding the Docker restart issue, you might be able to use the boot setting to execute a Docker auto-restart command.

As for file permission issues, they can be resolved by setting umask, fmask, and dmask, but I am not familiar with Linux permission settings and do not know the specific configuration. However, if you are not concerned about security risks, you could consider setting default = root in the user configuration (though this is not recommended).

Change Log

• 2022-10-24 Initial document creation.
• 2024-10-30
  • Changed shorthand commands to full commands.
  • Added instructions for uninstalling WSL.
  • Attempted to provide solutions for previous issues.
• 2026-01-22
  • Fixed the command for setting the default Linux distribution.