USB Passthrough in Proxmox VE: Complete Guide

Why USB Passthrough Matters

Many home servers and production environments rely on USB devices — Zigbee coordinators, Z-Wave dongles, USB hard drives, serial adapters, or security keys. Proxmox VE allows you to pass these devices directly into virtual machines or LXC containers so guest operating systems can use them as if they were physically connected. This is critical for home automation setups, backup appliances, and any workflow that depends on direct hardware access.

Unlike PCI passthrough, USB passthrough does not require IOMMU support and works on virtually any hardware. However, there are important differences between passing by device ID versus by port, and between VM and LXC container approaches.

Identifying Your USB Devices

Before configuring passthrough, identify the device on your Proxmox host. SSH into the node and run:

lsusb

You will see output like this:

Bus 002 Device 003: ID 1a86:55d4 QinHeng Electronics SONOFF Zigbee 3.0 USB Dongle Plus V2
Bus 001 Device 004: ID 0658:0200 Sigma Designs, Inc. Z-Wave Controller
Bus 001 Device 002: ID 0781:5581 SanDisk Corp. Ultra

Note the vendor and product ID (e.g., 1a86:55d4). You can also get more detail with:

lsusb -t          # shows the bus/port tree
lsusb -v -d 1a86:55d4  # verbose info for a specific device

USB Passthrough to Virtual Machines

Method 1: Pass by Device ID (Recommended)

Passing by vendor:product ID means the VM will always grab the correct device, even if you plug it into a different USB port. Use the qm set command:

# Syntax: qm set <vmid> -usb<N> host=<vendorid>:<productid>
qm set 100 -usb0 host=1a86:55d4

This adds the Zigbee dongle to VM 100. The device will be available after the next boot, or immediately if hotplug is enabled.

Method 2: Pass by USB Port

If you have multiple identical devices (e.g., two of the same USB serial adapter), passing by port ensures each VM gets the one plugged into a specific physical port:

# Find the bus-port path
lsusb -t

# Pass by bus and port number
qm set 100 -usb0 host=1-2

The downside is that if you move the device to another port, you must update the configuration.

Enabling USB Hotplug

By default, Proxmox VE supports USB hotplug for VMs using the QEMU XHCI (USB 3.0) controller. Make sure your VM uses the correct USB controller type:

# Add a USB 3.0 controller if not present
qm set 100 -machine q35
qm set 100 -usb0 host=1a86:55d4,usb3=1

With hotplug enabled, you can plug or unplug the USB device while the VM is running, and it will appear or disappear inside the guest OS without rebooting. You can also hotplug via the Proxmox web interface by navigating to the VM's Hardware tab and adding a USB device on the fly.

USB Passthrough to LXC Containers

LXC containers share the host kernel, so USB passthrough works differently. Instead of emulating USB hardware, you bind-mount the device node into the container. This is common for home automation controllers like Home Assistant.

Step 1: Find the Device Path

ls -la /dev/serial/by-id/
# Example output:
# usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2-if00 -> ../../ttyACM0

Step 2: Add the Mount Point

Edit the container configuration file directly:

nano /etc/pve/lxc/101.conf

Add these lines at the end:

# USB device passthrough
lxc.cgroup2.devices.allow: c 166:* rwm
lxc.mount.entry: /dev/ttyACM0 dev/ttyACM0 none bind,optional,create=file

The cgroup rule grants the container permission to access the character device, and the mount entry makes it visible inside the container. You need to find the correct major device number — use ls -la /dev/ttyACM0 to check (166 is typical for ACM devices).

Step 3: Set Device Permissions

If your container runs unprivileged, you may also need a udev rule on the host to set proper permissions:

# /etc/udev/rules.d/99-zigbee.rules
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="55d4", MODE="0666"

Reload udev rules and restart the container:

udevadm control --reload-rules && udevadm trigger
pct restart 101

Practical Examples: Zigbee and Z-Wave Dongles

Home automation is one of the most common reasons people pass USB devices through in Proxmox. Here is a typical setup for running Home Assistant in an LXC container with both a Zigbee and Z-Wave stick:

# /etc/pve/lxc/101.conf additions
lxc.cgroup2.devices.allow: c 166:* rwm
lxc.cgroup2.devices.allow: c 188:* rwm
lxc.mount.entry: /dev/ttyACM0 dev/ttyACM0 none bind,optional,create=file
lxc.mount.entry: /dev/ttyUSB0 dev/ttyUSB0 none bind,optional,create=file

Always use /dev/serial/by-id/ paths inside your home automation software configuration, even though you mount the short device name. The by-id symlinks are stable across reboots, while /dev/ttyACM0 numbering can change if you add or remove other USB devices.

Troubleshooting Common Issues

• Device not visible in VM: Verify the USB controller type. Switch from USB 2.0 (EHCI) to USB 3.0 (XHCI) in the VM hardware settings.
• Permission denied in LXC: Double-check the cgroup device allow rules and the major/minor numbers. Run stat /dev/ttyACM0 on the host to confirm.
• Device disappears after host reboot: Use by-id passthrough for VMs and add udev rules with MODE="0666" for LXC containers to ensure consistent access.
• Slow USB performance: Enable USB 3.0 mode (usb3=1) for storage devices passed to VMs.

If you manage multiple Proxmox nodes and need to track which USB devices are assigned where, tools like ProxmoxR can help you keep an overview of your hardware configurations across the cluster from a single dashboard.