About WSL

WSL | Windows Subsystem for Linux | Windows Linux subsystem

Some people may ask why they should install WSL. WSL is lighter, can be used to learn Linux and do development, and makes switching and interoperability between Windows and Linux more convenient. I first learned about it when using Docker on Windows. Also, it is fun 😋

About Terminal Software

You will keep using a terminal during the process. You can directly use the built-in Windows Terminal. Here are also a few terminal apps I recommend:

Tabby

I have been using it personally. The main reasons are that it is modern and good-looking, open source, supports plugins, and has Chinese support.

MobaXterm

It has both free and paid versions. The free version is enough. I have heard from others that it is useful, though it does not look very good (personally speaking).

Termius

It has mobile and desktop versions. I mostly use it on my phone to connect through SSH. GitHub Student Developer Pack includes it. It looks quite good, but it does not have Chinese.

Install WSL

1. Enable Windows Features

Search for “Turn Windows features on or off”.

Enable the two options below.

2. Install Linux and Move It to Another Drive

Open PowerShell in the terminal and set the default WSL version to WSL2.

1	wsl --set-default-version 2

Then enter the following command to list all available distributions.

1	wsl --list --online

For beginners, I recommend Ubuntu. I use Ubuntu-24.04 daily, but I also installed Arch Linux. If you like tinkering, you can try it. Choose according to your preference. Now start the installation.

1
2
3

wsl --install <the NAME of the distribution you chose>
# Example
wsl --install Ubuntu-24.04

When installing WSL2, you can use --location to specify the install location, for example:

1	wsl --install Ubuntu-24.04 --location D:\WSL\Ubuntu-24.04

Wait for the installation. If the download is slow, try changing your network environment.

After installation, follow the prompts to create a user and set a password.

The default distribution location is C:\Users\your-username\AppData\Local\wsl. If you install a lot of things later, it can take up a lot of space. The following is a migration guide for distributions installed without a specified location.

Enter exit to return to PowerShell, then enter the following command to export your distribution.

1
2
3

wsl --export <distribution name> <export path>
# Example
wsl --export Ubuntu-24.04 D:\WSL\Ubuntu-24.04\Ubuntu-24.04.tar

Then unregister the original distribution. This will also delete the distribution from the default location.

1
2
3

wsl --unregister <distribution name>
# Example
wsl --unregister Ubuntu-24.04

Import the exported distribution into the location you chose.

1
2
3

wsl --import <custom distribution name> <import location> <path to the exported .tar archive>
# Example
wsl --import Ubuntu-24.04 D:\WSL\Ubuntu-24.04 D:\WSL\Ubuntu-24.04\Ubuntu-24.04.tar

Now you can delete the exported .tar archive (keep it if you want it as a backup).

Here are some commonly used WSL commands:

wsl --list --verbose # Or wsl -l -v, list all installed distributions and their WSL versions
wsl --set-default <distribution name> # Set the default distribution, for example wsl --set-default Ubuntu-24.04
wsl --shutdown # Shut down all running distributions
wsl -d <distribution name> # Enter a distribution, for example wsl -d Ubuntu-24.04
wsl # Enter the default distribution

3. Configure Your Distribution

User Issues

Sometimes after entering your distribution, you may be the root user. This may be because you have not created another user. Find a tutorial to create one, then set the default user. Open the configuration file:

1	sudo vim /etc/wsl.conf

The section below sets the default user. Change it to your username.

Then exit, enter the following commands in PowerShell, and start the distribution again.

1 2	wsl --shutdown wsl -d Ubuntu-24.04

Detailed Configuration

There are many other settings for wsl.conf (distribution-specific settings, located at /etc/wsl.conf inside each distribution) and .wslconfig (global settings, located at C:\Users\your-username\.wslconfig on Windows). I will not go into detail here. For specific configuration methods, refer to Microsoft’s documentation: Advanced settings configuration in WSL

I recommend directly finding WSL Settings in the All apps section of the Start menu and using the graphical interface for global settings. It is more convenient and intuitive, and each option has a short explanation below it.

Here is my .wslconfig (settings adjusted in WSL Settings do not seem to appear in the .wslconfig file).

[wsl2]
memory=4GB # Memory
processors=8 # Number of processors
defaultVhdSize=30GB # Virtual hard disk size

[experimental]
sparseVhd=true # Make the distribution virtual disk use only the actual storage size instead of preallocating the maximum size

I do not quite understand sparseVhd=true. It does not seem very useful, and it may show a warning on startup, like this:

1
2
3

wsl: Sparse VHD support is currently disabled due to potential data corruption.
To force the distribution to use sparse vhd, run:
wsl.exe --manage  --set-sparse --allow-unsafe

Replace the Mirror Source

The default source may feel slow in China. In that case, you need to replace it with a mirror source.

I recommend using the mirror switching script LinuxMirrors.

Or change it manually:

Back up the original source list (optional)

1	sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak

Edit the source list file and replace it with a mirror source

1	sudo vim /etc/apt/sources.list.d/ubuntu.sources

Replace the following part in the file:

Types: deb
URIs: http://archive.ubuntu.com/ubuntu/
Suites: noble noble-updates noble-backports
Components: main universe restricted multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

With:

Types: deb
URIs: http://cn.archive.ubuntu.com/ubuntu/
Suites: noble noble-updates noble-backports
Components: main universe restricted multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

That is it. You can run the command below to try it.

1	sudo apt update && sudo apt upgrade -y && sudo apt autoclean && sudo apt clean && sudo apt autoremove

If you want to operate files on Windows from WSL, go to /mnt. It contains mounted folders for each Windows drive.

About WSLg

WSLg lets you run graphical applications from WSL on Windows. You can directly run graphical applications with commands inside WSL. Remember to make sure the following setting is enabled in WSL Settings.

Connect to WSL in VS Code

Some people may not be used to terminal editors. Next, here is a brief note on connecting to WSL in VS Code for file editing and development. Install the following extension:

Then you can connect to a WSL distribution from the Remote Explorer in the left sidebar.

Use Docker in WSL

It is best not to install Docker Desktop and an independent Docker engine inside WSL at the same time.

1. Integrate with Docker Desktop

First make sure Docker Desktop is installed on the Windows host, and enable Use the WSL 2 based engine in settings.

Then enable WSL integration in the following location, check the distributions where you want to use Docker, and remember to apply the settings.

Now you can directly use Docker in WSL to pull images and create containers.

Here are some commonly used Docker commands:

docker images # List all images, including images in Windows. These are managed by Docker Desktop
docker container ls # List all containers
docker volume ls # List all volumes
docker network ls # List all networks

docker rmi <image name/image ID> # Delete an image
docker container rm <container ID> # Delete a container
docker volume rm <volume name> # Delete a volume
docker network rm <network ID> # Delete a network

docker pull <various options> <container name:tag> # Pull an image
docker ps # View running containers
docker logs <container name/container ID> # View container logs. Optional parameters are available, ask AI about them

docker system prune # Clean up unused Docker resources. Use with caution

2. Install an Independent Docker Engine Inside WSL

I will not cover the specific installation method here. Please refer to the official Docker documentation.