Connecting USB devices to WSL
I’m a software engineer building tooling for Visual Studio and Visual Studio Code to support C++ embedded device development. These physical devices typically connect to a computer over USB, but we discovered we couldn’t use WSL to test our tools on Linux because it does not support USB. We weren’t alone — support for connecting physical USB devices to WSL is highly requested by the community as well.
While this functionality is still not natively available in WSL, I’m excited to announce that our summer intern, Nelson Daniel Troncoso Aldas, contributed changes to the open-source usbipd-win project to enable common developer USB scenarios like flashing an Arduino or accessing a smartcard reader.
To get started with this functionality, first ensure you’re running Windows 11 and have installed all WSL updates. Running
uname -a from within WSL should report a kernel version of 126.96.36.199 or later. You’ll need to be running a WSL 2 distro.
Install the latest release of usbipd-win.
From within WSL, install the user space tools for USB/IP and a database of USB hardware identifiers. The instructions below are for Ubuntu — other distributions may require a different usbip client package. On Ubuntu 20.04 LTS, run these commands:
sudo apt install linux-tools-5.4.0-77-generic hwdata sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/5.4.0-77-generic/usbip 20
At this point a service is running on Windows to share USB devices, and the necessary tools are installed in WSL to attach to shared devices.
Attaching a device
First ensure a WSL command prompt is open. This will keep the WSL 2 lightweight VM active.
From an administrator command prompt on Windows, run this command. It will list all the USB devices connected to Windows.
usbipd wsl list
Select the bus ID of the device you’d like to attach to WSL and run this command. You’ll be prompted by WSL for a password to run a sudo command.
usbipd wsl attach --busid <busid>
From within WSL, run
lsusb to list the attached USB devices. You should see the device you just attached and be able to interact with it using normal Linux tools. Note that depending on your application, you may need to configure udev rules to allow non-root users to access the device.
Once you are done using the device in WSL, you can either physically disconnect the device or run this command from an administrator command prompt on Windows.
usbipd wsl detach --busid <busid>
How it works
This functionality takes advantage of the USB/IP protocol to forward USB traffic over the virtual network interface between Windows and WSL. Code for USB/IP support has existed in the Linux kernel since 2009, but several recent changes made it easier to use in WSL.
- We updated the configuration options for the WSL Linux kernel to enable USB/IP support. This simplifies setup in WSL and avoids requiring users to build the kernel themselves.
- While support for attaching devices over USB/IP exists in Linux (a client), there was no corresponding server support for USB/IP in Windows. usbipd-win fills this gap. We contributed a command line interface to the project to both enable a USB device for sharing on Windows and attach it from within WSL.
We’d also like to give a shoutout to Frans van Dorsselaer, a system architect from the Netherlands who started usbipd-win. In his own words:
This started as a personal hobby project to get a single device working. I recently switched from VirtualBox to Hyper-V, but I was missing the USB passthrough functionality for my device. Unhappy with the existing solutions, either expensive commercial solutions or open-source projects that required unsigned drivers, I decided that I could do this! I read up on the USB standard, the USBIP implementation in the Linux kernel, and the VirtualBox driver source code. Next, a colleague of mine asked if his USB token would work too. Of course, it didn’t, but I decided to publish the project on GitHub and make it feature complete. Microsoft found my project and decided to help make it more mature with a proper management interface and support for WSL. And that is where we are now: configurable USB passthrough for Hyper-V and WSL.
Where to give feedback
We’re excited for you to try connecting USB devices to WSL. If you have feedback for this project, please open an issue on the open-source usbipd-win project. Learn more about WSL, including how to set up common development tools like Git, VS Code, Docker containers, databases, GPU acceleration for machine learning, and more, by visiting the WSL documentation. Finally, be on the lookout for future announcements from the C++ embedded development team about tooling to improve the embedded development experience regardless of device or compiler. Happy coding!