USB passthrough to KVM VMs with libvirt

Some software needs a physical USB device: a licence dongle, a Zigbee or Z-Wave stick for home automation, a serial adapter or a UPS. USB passthrough gives a KVM VM direct access to the device. (Proxmox users can use its GUI equivalent.)

Before you start

• Physical access to a KVM host you control; this is not possible on a rented VPS.
• The VM's name and libvirt access.

Find the device

lsusb

Example output: Bus 001 Device 004: ID 10c4:ea60 Silicon Labs CP210x UART Bridge. 10c4 is the vendor ID and ea60 the product ID.

Attach by vendor and product ID

Create usb-dongle.xml:

<hostdev mode='subsystem' type='usb' managed='yes'>
  <source>
    <vendor id='0x10c4'/>
    <product id='0xea60'/>
  </source>
</hostdev>

Attach permanently and to the running VM:

virsh attach-device homeassistant usb-dongle.xml --persistent --live

Detach with virsh detach-device and the same file.

Attach by bus and port

If you have two identical devices, IDs are ambiguous. Use the bus and device address instead:

<hostdev mode='subsystem' type='usb' managed='yes'>
  <source>
    <address bus='1' device='4'/>
  </source>
</hostdev>

Device numbers can change after unplugging or rebooting; ID-based matching is more stable when possible.

Check inside the guest

lsusb

ls /dev/ttyUSB* /dev/ttyACM*

Serial sticks appear as /dev/ttyUSB0 or similar.

USB controller type

Use a modern USB controller in the VM for USB 3 devices:

<controller type='usb' model='qemu-xhci'/>

Troubleshooting

• "Permission denied" or device busy: a host driver or service is using it (e.g. ModemManager grabbing serial sticks); stop or blacklist it.
• Device disappears after reboot: address-based passthrough with a changed device number; switch to vendor/product IDs.
• Device resets constantly: power-hungry devices on weak ports; use a powered hub or pass through the whole USB controller via PCI passthrough.
• AppArmor/SELinux denial: check host logs and adjust policy.

Frequently asked questions

Can I pass a whole USB controller?

Yes, as a PCI device with VFIO, which is more reliable for many devices; see PCI passthrough.

Does live migration work with USB passthrough?

No, the device is physically tied to one host.

Can I share a USB device over the network instead?

Tools such as USB/IP can export USB devices over a network, with some latency.

Next steps

• PCI and GPU passthrough
• Home lab virtualization
• virsh cheat sheet