Install Arch Linux on WSL

Arch Linux provides an official WSL (Windows Subsystem for Linux) image as part of the archlinux-wsl project.

Images are built and released monthly and aim to provide the simplest but complete system to offer an outright Arch Linux experience with WSL.

Note: These images are built for WSL 2. WSL 1 is not supported.

Installation

From a Windows system with WSL 2 installed, use one of the following installation methods.

Automated install

Warning: This automated install method is a work in progress and is not yet functional!

Run the following command in a PowerShell prompt:

> wsl --install archlinux

You can then run Arch Linux in WSL via the archlinux application from the Start menu, or by running wsl -d archlinux in a PowerShell prompt.

Manual install

WSL 2.4.4 or greater

Download the latest Arch Linux .wsl image and double-click on it to start the installation.

You can then run Arch Linux in WSL via the archlinux application from the Start menu, or by running wsl -d archlinux in a PowerShell prompt.

WSL prior to 2.4.4

Download the latest Arch Linux .wsl image and run the following command in a PowerShell prompt:

> wsl --import Distro_name Install_location WSL_image

For instance:

> wsl --import archlinux C:\Users\Username\AppData\Local\wsl\archlinux C:\Users\Username\Downloads\archlinux-2025.04.01.121271.wsl

You can then run Arch Linux in WSL via the archlinux application from the Start menu, or by running wsl -d archlinux in a PowerShell prompt. Make sure to execute the first setup script by running /usr/lib/wsl/first-setup.sh right after the first launch.

Tips and tricks

Set default user

To set a different default user than root, append the following to the /etc/wsl.conf file:

[user]
default=username

Note: This user has to exists on the WSL system (or else should be created).

The change will apply at the next session. To terminate your current session, run the following command in a PowerShell prompt:

> wsl --terminate archlinux

Run graphical applications with WSLg

WSLg (Windows Subsystem for Linux GUI) is a project that aims to enable running Linux applications with audio (PulseAudio) and graphical (X11 and Wayland) support within WSL.

To be able to run graphical applications with WSLg, enable GUI applications support in the %USERPROFILE%/.wslconfig file on your Windows system (create it if it does not exists) with the following content:

[wsl2]
guiApplications = true

With the the above set, WSL creates symlinks upon opening a session to the X11 and Wayland server's sockets but these are overriden by systemd during init. See microsoft/wslg#1032 for more details.

While waiting for upstream to resolve this problem, you can create the symlinks manually. First, create a systemd-tmpfiles configuration to link the directory containing the X11 server's socket:

/etc/tmpfiles.d/wslg.conf

#      Path         Mode UID  GID  Age Argument
L+     %T/.X11-unix -    -    -    -   /mnt/wslg/.X11-unix

Then, add the following to your ~/.bashrc to link the directory containing the PulseAudio and Wayland server's socket:

for i in "/mnt/wslg/runtime-dir/"*; do
  if [ ! -L "$XDG_RUNTIME_DIR$(basename "$i")" ]; then
    [ -d "$XDG_RUNTIME_DIR$(basename "$i")" ] && rm -r "$XDG_RUNTIME_DIR$(basename "$i")"
    ln -s "$i" "$XDG_RUNTIME_DIR$(basename "$i")"
  fi
done

Changes will apply at the next session. To terminate your current session, run the following command in a PowerShell prompt:

> wsl --terminate archlinux

Hardware accelerated rendering

To utilise hardware accelerated rendering in WSL, install the following packages:

mesa - Contains the d3d12 Gallium driver for OpenGL
vulkan-dzn - Contains the experimental dzn (also known as microsoft-experimental) Vulkan driver

You will need to install the vulkan-icd-loader (and lib32-vulkan-icd-loader if you also want to run 32-bit applications) as well.

WSL interoperability

WSL features interoperability between the Windows and WSL. This allows you to run Windows binaries from within WSL.

To use interoperability, make sure it is enabled in the /etc/wsl.conf file with the following content:

[interop]
enabled = true

Various tools have been created to allow you to utilise Windows services and features from within WSL.

Bridge the ssh-agent service from Windows

wsl2-ssh-agent is a tool that allows you to use the Windows SSH agent from within WSL.

This is especially useful if you utilise *-sk SSH keys requiring the use of physical security keys or even Windows Hello.

Install wsl2-ssh-agent^AUR and add the following to your ~/.bashrc:

eval "$(/usr/sbin/wsl2-ssh-agent)"

Restart your shell and the SSH_AUTH_SOCK environment variable should be configured correctly.

PAM authentication with Windows Hello

WSL-Hello-Sudo is a PAM plugin that allows you to authenticate your user via Windows Hello.

Install wsl-hello-sudo-bin^AUR and run /opt/wsl-hello-sudo/install.sh. The installer will copy a Windows executable to a directory of your choosing and store a certificate used to authenticate beside it.

Tip: https://github.com/nullpo-head/WSL-Hello-sudo has not been updated in 4 years, so wsl-hello-sudo-bin^AUR utilises a fork (https://github.com/lzlrd/wsl-hello-sudo) which has merged in dependency updates.

Add auth sufficient pam_wsl_hello.so to any /etc/pam.d configuration files you wish to authenticate with Windows Hello for. For example, with sudo:

/etc/pam.d/sudo

#%PAM-1.0
auth            sufficient      pam_wsl_hello.so
auth            include         system-auth
account         include         system-auth
session         include         system-auth

Passing devices to WSL

WSL 2 is a Hyper-V virtual machine. This allows for passthrough for physical devices from the host (Windows) to the guest (WSL 2).

Mount a disk

WSL 2 supports attaching and mounting disks available to Windows.

To do so, first idenitfy the DeviceID for the given disk with the following PowerShell command:

> GET-CimInstance -query "SELECT * from Win32_DiskDrive"

Once you have found the disk you would like to pass, run the following on Windows (with Administrator privileges):

> wsl --mount DeviceID --bare

Warning: This will take the disk offline in Windows! Make sure you have closed all running applications using the drive.

Once attached, you should be able to see the device with lsblk.

To unmount a disk, run:

> wsl --unmount DeviceID

For more information, see https://learn.microsoft.com/en-us/windows/wsl/wsl2-mount-disk.

Connect USB devices

usbipd-win is a project which allows for sharing locally connected USB devices to other machines, including WSL 2.

You first need to install the software on Windows. You can either run the installer (.msi) from the latest release or use use the Windows Package Manager:

> winget install usbipd

Once installed, identify the USB devices available using and take note of the bus ID by running the following on Windows:

> usbipd list

Prepare the USB device you have selected by running (this requires Administrator privileges):

> usbipd bind --busid busid

Warning: Make sure you have closed all running applications using the USB device.

Then, attach the USB device to WSL 2 using:

> usbipd attach --wsl --busid busid

Once attached, you should be able to see the device with lsusb.

To detatch a USB device, run:

> usbipd detach --busid busid

For more information, see https://learn.microsoft.com/en-us/windows/wsl/connect-usb.

Troubleshooting

systemd support

The Arch Linux WSL image provides systemd support.

However, there are known pending issues that may require additional actions for systemd to work properly.

systemd-firstboot.service hanging

The systemd-firstboot.service job hangs at first boot, preventing any other systemd services to start.

While waiting for the actual root cause of this issue (and a proper fix for it) to be identified, a workaround is automatically applied by the first-setup script when running the image for the first time, so you should not have to do anything on that front.

See archlinux/archlinux-wsl#3 for more details.

systemd requires plain cgroup v2 support

Currently, WSL starts systems with cgroup v1 support by default[1] but systemd >= 256 dropped support for it[2] and requires plain cgroup v2 support.

While waiting for WSL to start systems with plain cgroup v2 support by default, you can force it by disabling cgroup v1 support in the %USERPROFILE%/.wslconfig file on your Windows system (create it if it does not exists) with the following content:

[wsl2]
kernelCommandLine = cgroup_no_v1=all systemd.unified_cgroup_hierarchy=1