[ About | Licence | Contacts ]
Written by Oleksandr Gavenko (AKA gavenkoa), compiled on 2024-04-01 from rev 052223c22317.

WSL, Windows subsystem for Linux


Windows Subsystem for Linux Documentation.
Awesome list dedicated to Windows Subsystem for Linux.
Automatically Configuring WSL.
Troubleshooting Windows Subsystem for Linux.
Awesome list dedicated to Windows Subsystem for Linux.

wsl utility

Run Linux command from default distro:

wsl ls
wsl -e /bin/ls
wsl --exec /bin/bash

Run Linux command from specific distro:

wsl -d ubuntu ls
wsl -d debian -e /bin/ls
wsl -d debian --exec /bin/bash
wsl -distribution debian --exec /bin/bash

Run Linux command from specific user:

wsl -u user ls
wsl --user root ls

Combining user & distro:

wsl -u root -d alpine -- ls
wsl -u root -e sh -c "service apache status || service apache start"
Ways to run WSL.


Earlier wsl utility was limited and some job performed by wslconfig utility:

  • List distros:

    wslconfig /l
    wslconfig /list
  • Set default distro:

    wslconfig /s debian
    wslconfig /setdefault debian
  • Terminate any running parts of distro:

    wslconfig /t debian
    wslconfig /terminate debian

Installing WSL distor second time

Microsoft provides certain Linux distros out of the box:

wsl --list --online
Ubuntu          Ubuntu
Debian          Debian GNU/Linux
kali-linux      Kali Linux Rolling
openSUSE-42     openSUSE Leap 42
SLES-12         SUSE Linux Enterprise Server v12
Ubuntu-16.04    Ubuntu 16.04 LTS
Ubuntu-18.04    Ubuntu 18.04 LTS
Ubuntu-20.04    Ubuntu 20.04 LTS

After the installation you will have an executable NAME.exe for convenient entering into distro, compare:

$ wsl -d NAME CMD
$ NAME.exe CMD

You install such distros via:

wsl --install NAME

What if you want 2 Debian distros? Unfortunately you have to deal with rootfs:

I'd suggest to use Ubuntu "base" images instead (less bloated than "cloud" images):

You download rootfs and import it:

wget http://cdimage.ubuntu.com/ubuntu-base/releases/22.04/release/ubuntu-base-22.04-base-amd64.tar.gz
wsl --import my-ubuntu c:\wsl\my-ubuntu ubuntu-base-22.04-base-amd64.tar.gz --version 2

Mounting Windows file systems

From January 2018 WSL 1 allows to mount external NTFS file systems as drvfs. metadata option allows chmod operation on NTFS volumes, metadata will be shared across all WSL distros though.

Chmod/Chown WSL Improvements.

To preserve customization between WSL reloads update /etc/wsl.conf with something like:

enabled = true
mountFsTab = false
options = "metadata,noatime,uid=1000,gid=1000,umask=022,fmask=077"

Equivalent CLI call is:

sudo mount -t drvfs 'C:\' /mnt/c -o metadata,noatime,uid=1000,gid=1000,umask=022,fmask=077
Automatically Configuring WSL.

To mount attached USB stick:

sudo mkdir /mnt/f
sudo mount -t drvfs f: /mnt/f
/etc/wsl.conf configuration options.

Switching WSL version

Set default version for new containers:

wsl --set-default-version 1

Convert a specific distro to WSL 1 or 2:

wsl --set-version Debian 1
wsl --set-version Alpne 2

Debugging WSL

https://github.com/Microsoft/WSL/blob/master/CONTRIBUTING.md https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/wsl.wprp https://github.com/Microsoft/WSL/blob/master/diagnostics/collect-wsl-logs.ps1

https://msrc-blog.microsoft.com/2018/12/10/first-steps-in-hyper-v-research/ https://msrc-blog.microsoft.com/2019/09/11/attacking-the-vm-worker-process/

Custom WSL 2 Linux kernel

Register kernel in /etc/wsl.conf:


Enabling trimming

wsl --manage $NAME --set-sparse true
wsl --manage $NAME --set-sparse false

or in .wslconfig:

Automatic disk space clean up (Set sparse VHD).

Legacy solutions were based on re-importing existing image, like:

Compacts the size of the ever-growing WSL vhdx images.

or filling with zeros and processing VHD:

sudo dd if=/dev/zero of=/0bits bs=20M + Optimize-VHD.

Check TRIM support in the distro:

sudo apt install hdparm
sudo hdparm -I /dev/sdc