How to Access a USB Device from WSL2

wsl2-usb-device-guide.md

How to Access a USB Device from WSL2

If you use Windows Subsystem for Linux 2 (WSL2), you've probably noticed that USB devices do not automatically appear inside your Linux environment. That's by design: WSL2 runs in a lightweight VM, so direct hardware access works differently than it does on a native Linux machine.

The supported way to pass a USB device from Windows into WSL2 is with usbipd-win, a Windows tool that exposes USB devices to WSL over USB/IP.

This guide walks through the setup and shows how to attach, verify, and detach a USB device from WSL2.

When This Is Useful

This setup is especially helpful for:

• Arduino and other microcontroller boards
• USB serial adapters
• ST-Link / J-Link debuggers
• Smart card readers
• Other developer-focused USB peripherals

Prerequisites

Before you start, make sure you have:

• WSL2, not WSL1
• A recent version of WSL
• Windows 11, or the Microsoft Store version of WSL on Windows 10
• A USB device physically connected to your Windows machine
• A WSL kernel version of 5.10.60.1 or later

You can check your WSL version and update it from PowerShell:

wsl --version
wsl --update

Step 1: Install usbipd-win

Microsoft's recommended approach uses the open-source usbipd-win project.

Install it with winget:

winget install --interactive --exact dorssel.usbipd-win

This installs:

• The usbipd command-line tool
• A Windows service for USB/IP
• Firewall rules needed for local access

If you prefer, you can also install it from the project's GitHub releases page.

Step 2: Keep a WSL Terminal Open

Before attaching a device, open your WSL distro once so the WSL2 VM is running:

wsl

Leave that terminal open.

Step 3: List Available USB Devices

Open PowerShell as Administrator and run:

usbipd list

You'll see output similar to this:

BUSID  DEVICE                                      STATE
1-7    USB Input Device                            Not shared
4-4    STMicroelectronics STLink dongle            Not shared
5-2    Surface Ethernet Adapter                    Not shared

Find the device you want and note its BUSID.

Step 4: Share the Device with WSL

Still in the Administrator PowerShell, bind the device:

usbipd bind --busid 4-4

Replace 4-4 with your actual bus ID.

You only need to do this once per device in most cases. The sharing state is persistent across reboots.

You can verify the device is shared:

usbipd list

The state should now show as Shared.

Step 5: Attach the Device to WSL2

Now open a regular, non-admin PowerShell window and run:

usbipd attach --wsl --busid 4-4

Once attached:

• Windows can no longer use that device while it is attached to WSL
• Any running WSL2 distro can access it

Step 6: Verify the Device Inside WSL

In your Linux shell, run:

lsusb

If the device is attached successfully, it should appear in the output.

If lsusb is not installed, install it on Ubuntu/Debian with:

sudo apt update
sudo apt install usbutils

Depending on the device, you may also see a Linux device node such as:

• /dev/ttyUSB0
• /dev/ttyACM0
• /dev/hidraw0

For serial devices, this is often the real endpoint your Linux tools will use.

Step 7: Detach the Device When You're Done

From PowerShell, detach the device:

usbipd detach --busid 4-4

After detaching, Windows can use the device again.

Troubleshooting

lsusb Shows the Device, But My App Cannot Access It

This is usually a Linux permissions issue, not an attachment problem. You may need a udev rule so non-root users can access the hardware.

For example, embedded tools like openocd often require matching udev rules.

After updating rules, reload them with:

sudo udevadm control --reload

If that fails, try:

sudo service udev restart

The Device Does Not Appear in WSL

Check these common causes:

• Your distro is running as WSL2, not WSL1
• WSL is updated: wsl --update
• The device was successfully bound with usbipd bind
• The device is actually attached: usbipd list
• A WSL shell was open before attaching

What About USB Flash Drives or External Disks?

This is the main exception.

If your goal is to access a USB storage drive, the simplest approach is usually:

• Let Windows mount it
• Access it from WSL under /mnt/<drive-letter>

Example:

cd /mnt/d

Microsoft also notes that wsl --mount does not currently support USB flash drives or SD card readers.

Do You Need Extra Kernel Work?

Usually, no.

Current WSL kernels already support many common development scenarios, including USB serial adapters and flashing embedded boards. You should only need a custom WSL kernel if your hardware depends on a driver that is not already present.

Final Notes

Once usbipd-win is installed, the workflow is straightforward:

1. List devices with usbipd list
2. Bind once with usbipd bind --busid ...
3. Attach with usbipd attach --wsl --busid ...
4. Use the device from Linux
5. Detach when finished

For most developer USB devices, this is the cleanest and officially documented way to make WSL2 behave more like a native Linux environment.

Sources

• Microsoft Learn, Connect USB devices: https://learn.microsoft.com/en-us/windows/wsl/connect-usb
• Microsoft Learn, Mount a Linux disk in WSL 2: https://learn.microsoft.com/en-us/windows/wsl/wsl2-mount-disk
• usbipd-win WSL support wiki: https://github.com/dorssel/usbipd-win/wiki/WSL-support