Connecting USB Devices To Docker Containers On Windows Via WSL2

August 3, 2025 by StackCamp Team 64 views

How to Connect a USB Device to a Docker Container on Windows via WSL2

Connecting USB devices to Docker containers on Windows, especially when using Windows Subsystem for Linux (WSL2) and Docker Desktop, can be a bit tricky. But don't worry, guys! We're going to break it down step by step. This guide will walk you through how to attach a USB device on a Windows host, then pass it to a Linux Docker container. We'll focus on using usbipd-win to connect a J-Link device, but these steps can be adapted for other USB devices as well. Let's dive in!

Prerequisites

Before we get started, make sure you have the following:

Windows 11: This guide is tailored for Windows 11, but similar steps can be used for Windows 10.
WSL2: Windows Subsystem for Linux 2 must be installed and enabled. WSL2 provides a Linux environment that plays nicely with Docker.
Docker Desktop: Docker Desktop for Windows is essential for running Docker containers. Make sure it's up and running.
Ubuntu 24.04: We'll be using an Ubuntu 24.04 image for our Docker container, but you can adapt these instructions for other Linux distributions.
usbipd-win: This tool allows you to share USB devices from Windows to WSL2.
J-Link device (or other USB device): In this example, we're connecting a J-Link device, but the process is similar for other USB devices.

Having these prerequisites in place will ensure a smooth setup process. Trust me, you don't want to skip any of these!

Step 1: Installing and Configuring `usbipd-win`

First things first, let’s get usbipd-win installed and configured. This is a crucial step because usbipd-win acts as the bridge between your Windows host and the WSL2 environment, allowing you to share USB devices.

Installation

Download usbipd-win: Head over to the usbipd-win GitHub repository (https://github.com/usbip/usbipd-win) and download the latest release. Look for the .msi installer file. This is where the magic begins, guys!
Run the Installer: Double-click the .msi file and follow the installation prompts. Make sure to install it with administrative privileges. This ensures that the necessary system components are correctly set up. Don't skip this step.
Enable WSL Support: During the installation, you’ll be prompted to enable WSL support. Make sure this option is checked. This is vital for the integration between usbipd-win and your WSL2 environment. Trust me, you need this!

Configuration

Open PowerShell as Administrator: Right-click on the Start menu and select “Windows PowerShell (Admin)” or “Windows Terminal (Admin)”. Running as an administrator ensures that you have the necessary permissions to execute the commands.
List Attached USB Devices: Use the following command to list all USB devices attached to your Windows host:
```
usbipd wsl list
```
This command will display a list of USB devices, including their bus IDs. Take note of the bus ID of your J-Link device (or the USB device you want to connect). You'll need this in the next step. Make sure you write it down!
Attach the USB Device to WSL2: Use the following command to attach the USB device to your WSL2 environment, replacing <bus ID> with the actual bus ID of your device:
```
usbipd wsl attach --busid <bus ID>
```
For example, if your device's bus ID is 1-2, the command would be:
```
usbipd wsl attach --busid 1-2
```
This command forwards the USB device to your WSL2 environment, making it accessible from within Linux. This is where the magic happens!
Verify the Attachment in WSL2: Open your WSL2 terminal (e.g., Ubuntu) and run the following command to verify that the device is attached:
```
lsusb
```
You should see your J-Link device (or other USB device) listed in the output. If you see it, congrats! You’ve successfully attached the USB device to your WSL2 environment.

Troubleshooting

Device Not Listed: If your device is not listed when running usbipd wsl list, make sure it’s properly connected to your Windows host. Try unplugging and replugging the device.
Attachment Failed: If the attachment fails, ensure that you’re running PowerShell as an administrator and that the bus ID is correct.

Step 2: Setting Up the Docker Container

Now that we've attached the USB device to WSL2, the next step is to set up our Docker container. We'll create a Dockerfile and configure it to access the USB device.

Creating the `Dockerfile`

Create a New Directory: Create a new directory for your Docker project. This helps keep everything organized.
```
mkdir docker-jlink
cd docker-jlink
```
Create a Dockerfile: Inside the directory, create a file named Dockerfile (without any file extension). This file will contain the instructions for building your Docker image. This is where the magic recipe goes!
Add the Following Content to the Dockerfile: This Dockerfile is tailored for Ubuntu 24.04 and includes the necessary steps to install USB utilities and the J-Link software. You can adjust it based on your specific needs.
```
# Use Ubuntu 24.04 as the base image
FROM ubuntu:24.04

# Set environment variables to avoid interactive prompts
ENV DEBIAN_FRONTEND=noninteractive

# Update package lists and install necessary dependencies
RUN apt-get update && apt-get install -y \
    usbutils \
    libusb-1.0-0-dev \
    wget \
    apt-transport-https \
    ca-certificates

# Download and install J-Link software (replace with the actual URL)
RUN wget https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.tgz && \
    tar -xzf JLink_Linux_x86_64.tgz && \
    cd JLink && \
    ./install && \
    cd .. && \
    rm -rf JLink JLink_Linux_x86_64.tgz

# Clean up APT cache
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

# Set the working directory
WORKDIR /app

# Command to run when the container starts
CMD ["/bin/bash"]
```
Let’s break down what this Dockerfile does:
- FROM ubuntu:24.04: Sets the base image to Ubuntu 24.04. This is the foundation of our container.
- ENV DEBIAN_FRONTEND=noninteractive: Prevents interactive prompts during package installations. No annoying pop-ups!
- RUN apt-get update && apt-get install -y ...: Updates the package lists and installs necessary dependencies like usbutils (for USB device listing), libusb-1.0-0-dev (for USB communication), and other utilities.
- RUN wget ... && tar ... && ./install ...: Downloads and installs the J-Link software. Make sure to replace the URL with the actual download link from Segger’s website!
- RUN apt-get clean && rm -rf /var/lib/apt/lists/*: Cleans up the APT cache to reduce the image size. Keep it lean and mean!
- WORKDIR /app: Sets the working directory inside the container.
- `CMD [