Intro

WSL: Windows Subsystem for Linux

WSL is a tiny Linux VM embedded in Windows, default is Ubuntu.

Homepage: https://github.com/microsoft/WSL

One-Click Install (Online Install)

wsl --install

Issue: wsl --install is very slow, mainly because Microsoft’s overseas servers have poor bandwidth in China. Fastest solution: Offline manual install (domestic mirror download), done in a few minutes.

Manual Install (Offline Install)

Prerequisites

Windows 11 Home fully supports WSL2, no Hyper-V required. Just enable two system features, install the MSI you downloaded, and import the wsl image - works fully offline.

Step 0: Download

wsl program

From https://github.com/microsoft/WSL/releases， download wsl.2.7.3.0.x64.msi file

Ubuntu wsl file

According to the https://github.com/microsoft/WSL/blob/master/distributions/DistributionInfo.json file, it contains URLs for all distros.

Find the WSL image download link from https://releases.ubuntu.com/26.04/, download ubuntu-26.04-wsl-amd64.wsl file

Place both files in an all-English path, e.g., D:\wsl

Additional Domestic High-Speed Links (unverified)

Use browser / Xunlei to download:

  1. WSL2 Kernel (msi)
  2. Ubuntu 22.04 (tar.gz) (Tsinghua Mirror)

Save to: D:\wsl\ (pure English path)

Step 1: Enable Required WSL System Features

  1. Right-click Start menu → select Windows Terminal (Admin) or PowerShell (Admin)
  2. Execute these two commands in sequence, no restart needed:

powershell

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  1. Restart computer to take effect

Step 2: Install WSL Core MSI Package

  1. Locate your downloaded wsl.2.7.3.0.x64.msi
  2. Double-click to install, just click Next through the defaults
  3. Close the window after installation, no extra configuration needed

Step 3: Import Ubuntu26.04 .wsl Image

Double-click the ubuntu-26.04-wsl-amd64.wsl file, it will import automatically.

During import, it will prompt you to enter username and password

You can also manually import with these steps:

  1. Create a new pure English path folder (preferably not on C drive), e.g., D:\WSL\Ubuntu2604
  2. Place the downloaded ubuntu-26.04-wsl-amd64.wsl in a path with no Chinese characters, no spaces, e.g., D:\WSL\
  3. Open regular PowerShell (not admin), execute the import command:
wsl --import Ubuntu2604 D:\WSL\Ubuntu2604 D:\WSL\ubuntu-26.04-wsl-amd64.wsl --version 2

Parameter explanation:

  • Ubuntu2604: custom distro name (can change)
  • D:\WSL\Ubuntu2604: directory to store WSL system files
  • Last is the full path to your .wsl file
  • --version 2: force WSL2

Step 4: Initialize and Use Ubuntu

  1. Start the imported system:

In powershell

wsl -d Ubuntu2604
// Command line will automatically enter the VM's shell
  1. First launch will prompt you to create Linux username and password, follow the prompts to set it
  2. Verify if it’s WSL2:

In powershell

wsl -l -v
// -l means list
// -v means verbose output, will output version

If version shows 2, you’re successful

Common Issues

  1. Import error due to Chinese / spaces in path: change all files and folders to English without spaces
  2. Stuck on initialization: run wsl --shutdown then restart
  3. Want to set as default: wsl --set-default Ubuntu2604
  4. Want to uninstall: wsl --unregister Ubuntu2604

wsl Commands

Start VM

Run wsl -d <distro-name>, it will start the distro’s VM and enter its shell

Create and Change Default User

# Create user (replace with desired name)
useradd -m -G sudo -s /bin/bash yourname
passwd yourname

# Set as default user
echo -e "[user]\ndefault=yourname" >> /etc/wsl.conf

Shutdown / Reboot VM

wsl --terminate Ubuntu wsl -d Ubuntu

More Resources