Install Arch Linux on WSL - ArchWiki

Jump to content

# Install Arch Linux on WSL

1 language

- 中文（简体）

From ArchWiki

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`, first ensure the user has been created, then append the following to the `/etc/wsl.conf` file:

    [user]
    default=username

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, create the following file to link the directory containing the PulseAudio and Wayland server's socket as well as set the Gallium driver:

    /etc/profile.d/wslg.sh

    export GALLIUM_DRIVER=d3d12

    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.

if openGL falling back to llvmpipe software renderer on Intel GPUs, you need to link libedit (sudo ln -s /usr/lib64/libedit.so.0 /usr/lib64/libedit.so.2 ), see https://github.com/microsoft/wslg/issues/996 and https://wiki.gentoo.org/wiki/Gentoo_in_WSL and you also need to export GALLIUM_DRIVER=d3d12 according to https://github.com/microsoft/wslg/issues/996#issuecomment-2720501874

### 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-agentAUR 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-binAUR 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-binAUR 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

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

    > wsl --terminate archlinux

### Failure when running Docker containers

One might face the following error when running a Docker container from WSL:

    Error response from daemon: path / is mounted on / but it is not a shared or slave mount
    Error: failed to start containers

This is because Docker expects the root (`/`) directory to be mounted with rshared propagation.

To do so, run:

    # mount --make-rshared /

## See also

- Wikipedia:Windows Subsystem for Linux
- Gentoo:Gentoo in WSL
- Official Documentation
- WSLg GitHub Wiki

Categories:

- Installation process
- Hypervisors