Not every device you want inside a VM or container is a disk image or a virtual NIC. Software license dongles, DVB-T/S tuners, serial-to-USB adapters for talking to network gear, security keys like YubiKeys, barcode scanners, and even webcams all show up as physical USB hardware attached to your Proxmox VE host — and none of them are visible to a guest unless you explicitly pass them through. Unlike GPU passthrough, which depends on IOMMU groups, VFIO binding, and firmware quirks, USB passthrough on Proxmox VE is comparatively simple: the hypervisor already owns the USB controller, so handing a single device to a guest is mostly a matter of telling QEMU (or the LXC device-passthrough layer) which one to hand over.

That simplicity hides a few sharp edges, though. Device IDs aren't always unique, USB ports get renumbered when you move hardware to a different host, VMs need a full stop/start rather than a reboot to pick up a new device, and containers add a permissions layer that VMs don't have to worry about. This guide walks through both paths — VM passthrough via qm and the GUI, and LXC passthrough via pct — plus the cluster-wide Resource Mapping feature that makes USB passthrough survive VM migrations between nodes with different physical hardware.

Everything here is current for Proxmox VE 9.2.x. The underlying mechanism has been stable across PVE 7 and 8 as well, with the main addition in 8.x being LXC device passthrough without manual cgroup rules, and in 8.1+ the Resource Mapping UI for both USB and PCI devices.

How USB Passthrough Actually Works

For virtual machines, Proxmox VE doesn't need the IOMMU-based isolation that PCI/GPU passthrough requires. QEMU emulates a USB host controller (UHCI/EHCI for USB 2.0, XHCI for USB 3.0) inside the VM, and a usb-host device attaches a specific physical device — identified either by its USB vendor/product ID or by its physical bus/port location — to that virtual controller. The host's kernel driver for that device is unbound while the VM has it claimed, then rebound when it's released.

For LXC containers, there's no device emulation at all — containers share the host kernel, so passthrough is really just exposing a device node (like /dev/bus/usb/001/005) inside the container's filesystem and granting the container's cgroup permission to access it.

One hard limitation applies to both: only real, single-function devices can be passed through. USB hubs cannot be passed through as a unit — you have to pass through the individual devices behind the hub. If a device disappears and reappears on a different port, ID-based mapping still finds it; port-based mapping does not, since it's tied to physical topology, not device identity.

Identifying Your USB Device

Before touching any VM or container config, identify the device on the Proxmox host itself, over SSH or the host shell:

lsusb

This lists every USB device the host currently sees, in the form:

Bus 003 Device 004: ID 058f:6387 Alcor Micro Corp. Flash Drive
Bus 001 Device 002: ID 8087:0aa7 Intel Corp. Bluetooth wireless interface

The 058f:6387 pair is the vendor ID and product ID — this identifies the type of device, not the specific physical unit. If you plug in two identical flash drives, they'll show the same ID pair, which is exactly the scenario where you'd want physical port mapping instead (covered below).

To see the physical topology — which port each device is actually plugged into — run:

lsusb -t

This prints a tree showing bus and port numbers, e.g. Bus 3, Port 1, sub-port 2 becomes the identifier 3-1.2. If a VM is already running, you can also query live USB info through its QEMU monitor:

qm monitor 804
info usbhost

The info usbhost output lists bus, device address, port, and negotiated speed for everything the host sees — a 12 Mb/s link is USB 1.1, 480 Mb/s is USB 2.0, and 5000 Mb/s (or higher, for 3.1/3.2 devices) is USB 3.0 and above. That speed number matters because it tells you which virtual controller to attach the device to.

Part 1: USB Passthrough for Virtual Machines

Method A — Via the Web GUI

The simplest path for a one-off device:

  1. Select the target VM in the Proxmox VE web interface.
  2. Go to Hardware → Add → USB Device.
  3. Choose Use USB Vendor/Device ID to bind by device type, or Use USB Port to bind by physical location.
  4. Pick the device from the dropdown (it's populated live from what the host currently sees).
  5. If the device negotiates at 5000 Mb/s or faster, tick USB3 so it's attached to the emulated XHCI controller instead of the slower EHCI one.
  6. Click Add, then fully stop and start the VM — a reboot from inside the guest is not enough, since the USB device attachment happens at QEMU process launch, not during guest boot.

Method B — Via the CLI with qm

The same operation from the shell, for scripting or when you already know the IDs. Bind by vendor:product ID:

qm set 804 -usb0 host=058f:6387

Bind by physical port instead, useful when you have multiple identical devices and need to guarantee which physical port maps to which VM:

qm set 804 -usb1 host=3-1.2

For a USB 3.0 device on Proxmox VE 4.0 and later, add the usb3 flag so QEMU attaches it to the XHCI controller rather than the default EHCI one:

qm set 804 -usb0 host=058f:6387,usb3=yes

Both forms write directly into the VM's configuration file at /etc/pve/qemu-server/804.conf, where you'll see a line like:

usb0: host=058f:6387,usb3=1

You can hold up to 14 USB devices per VM (usb0 through usb13 in recent QEMU machine types), though in practice you'll rarely need more than one or two.

Hot-Plugging a Device Into a Running VM

If the VM is already running and you don't want to restart it, attach through the QEMU monitor instead of editing the config permanently:

qm monitor 804
device_add usb-host,vendorid=0x058f,productid=0x6387,id=hotusb1

Or by physical port:

device_add usb-host,hostbus=3,hostport=1.2,id=hotusb1

To remove it cleanly, make sure the device is unmounted or otherwise not in active use inside the guest OS first, then:

device_del hotusb1

Monitor hot-plugging is session-only — it doesn't persist across a VM restart. For a permanent attachment, use qm set as shown above, or remove a persistent entry with:

qm set 804 -delete usb0

Part 2: Cluster-Wide Resource Mappings

Hardcoding a vendor:product ID or bus-port string directly into a VM config works fine on a single node, but it breaks the moment you migrate that VM to a different host in a cluster — the new node might not have an identical device in an identical port, or might number its buses differently. Proxmox VE's Resource Mapping feature (Datacenter → Resource Mappings, alongside the equivalent PCI mapping feature) solves this by giving a device a cluster-wide logical name that's resolved per-node.

To create one from the GUI: go to Datacenter → Resource Mappings → Add → USB Device, give it a name (e.g. license-dongle), and for each node in the cluster where a matching physical device exists, add the corresponding vendor/product ID or port path. Once defined, reference the mapping in a VM instead of a raw device string:

qm set 804 -usb0 mapping=license-dongle

The VM config file then stores usb0: mapping=license-dongle rather than a hardware-specific string, and Proxmox resolves it to the correct physical device on whichever node the VM actually starts on. You can also manage mappings entirely from the CLI via pvesh:

pvesh get /cluster/mapping/usb --output-format json

Access to mappings is governed by two distinct privileges: Mapping.Modify, which lets a user create or edit the cluster-wide mapping definitions themselves (a Datacenter-level operation, appropriately restricted to admins), and Mapping.Use, which lets a user attach an existing mapping to a VM they control without being able to alter what that mapping actually points to. This split is exactly what you want in a multi-tenant setup — a delegated VM owner can plug a named device into their own guest, but can't repoint what "license-dongle" resolves to on the underlying hardware.

Part 3: USB Passthrough for LXC Containers

Containers don't get an emulated USB controller — since they share the host kernel, passthrough here means exposing the raw device node inside the container and granting cgroup permission to touch it. Proxmox VE 8.0 and later ship a proper device-passthrough feature that handles both parts in one command, and it works for unprivileged containers as well as privileged ones — a real improvement over the manual method it replaced.

Modern Method — Device Passthrough (PVE 8.0+)

First, confirm the device node the host assigned it, e.g. via lsusb combined with:

ls -l /dev/bus/usb/001/

Then attach it to a container:

pct set 105 --dev0 path=/dev/bus/usb/001/005

This creates the corresponding device node inside the container at boot, without requiring you to hand-write cgroup allow rules or bind-mount entries — Proxmox handles both the mount and the permission grant, and reapplies them correctly even for unprivileged containers where UID/GID mapping would otherwise make a manual bind mount inaccessible to the container's user. You can also add read-only mode or specific UID/GID ownership inside the container:

pct set 105 --dev0 path=/dev/bus/usb/001/005,uid=100000,gid=100000

As with VMs, a plain reboot from inside the container config apply doesn't always re-probe hot-plugged devices reliably — a full pct stop/pct start is the safe way to confirm a new mapping takes effect.

Legacy Method — Manual cgroup Rules and Bind Mounts

On older Proxmox VE 7.x hosts, or where you need finer control, the equivalent config is written by hand into /etc/pve/lxc/105.conf. For a generic USB device by its device-node major number (189 covers /dev/bus/usb/* nodes):

lxc.cgroup2.devices.allow: c 189:* rwm
lxc.mount.entry: /dev/bus/usb/001/005 dev/bus/usb/001/005 none bind,optional,create=file

For a USB serial adapter exposed as /dev/ttyUSB0 (major number 188), the rule is nearly identical:

lxc.cgroup2.devices.allow: c 188:* rwm
lxc.mount.entry: /dev/ttyUSB0 dev/ttyUSB0 none bind,optional,create=file

Two details trip people up here every time: the lxc.mount.entry target path is relative to the container root, so it must read dev/ttyUSB0, not /dev/ttyUSB0 — a leading slash silently produces an empty mount. And this manual method requires a privileged container in most configurations, since unprivileged containers remap UIDs/GIDs in a way that breaks direct device-node bind mounts unless you also work out the mapped IDs by hand — which is precisely the headache the PVE 8.0+ pct set --devN feature exists to remove.

Common Pitfalls

  • Multiple identical devices. Two USB drives from the same manufacturer and model report the same vendor:product ID. If you bind by ID, Proxmox can't tell them apart and may attach whichever one it finds first. Use physical port mapping (host=3-1.2) instead, and label your ports.
  • Hubs can't be passed through. Only "real" downstream devices are assignable. If a device sits behind a hub (including many all-in-one card readers and internal front-panel headers), you pass through the specific device, never the hub itself.
  • A guest reboot isn't a re-attach. Both QEMU and the LXC device layer bind a USB device when the VM/container process starts, not each time the guest OS reboots. Adding or changing a passthrough entry requires a full stop and start.
  • Ports get renumbered. If you move a drive to a different physical port, or swap a USB hub for a different model, the bus-port string changes and a port-based mapping silently stops matching. ID-based mapping is more resilient to this but reintroduces the duplicate-ID problem above — pick the tradeoff that matches your hardware.
  • No live migration with locally-attached USB. A device physically plugged into one node's chassis can't follow a VM during a live migration to another node — there's no hardware on the target host to hand over. Resource Mapping solves the configuration portability problem (the VM config resolves correctly on the new node) but only if a matching physical device is actually present there; if it isn't, the VM will fail to start until you remove or update the passthrough entry.
  • Permissions on unprivileged containers. If you hit "Permission denied" accessing a passed-through device inside an unprivileged LXC container using the manual method, it's almost always the UID/GID remap biting you — switch to pct set --devN, which is UID/GID-remap aware, rather than hand-tuning ownership.

Security Considerations

USB passthrough hands a guest direct, low-level access to a physical device — including, for certain device classes, more of the host's USB stack than you might expect. Treat any VM or container with USB passthrough enabled as having a slightly larger trust boundary than one without: a compromised guest with a passed-through storage device can read and write that device directly, and a malicious or malfunctioning USB device (a so-called "BadUSB" scenario) is exposed straight to the guest without any host-side mediation. For shared or multi-tenant hosts, restrict Mapping.Modify to administrators, grant Mapping.Use only to the specific users who need a given device, and avoid passing through storage devices you haven't physically vetted.

Frequently Asked Questions

Can I pass the same USB device to two VMs at once?
No. A USB device can only be claimed by one guest (or the host) at a time. Attaching it to a second VM while the first still holds it will fail or silently steal it depending on timing — always detach cleanly from one guest before attaching to another.

Do I need IOMMU enabled for USB passthrough, like I do for GPU passthrough?
No. IOMMU/VT-d is required for PCI(e) device passthrough because the host has to prove DMA isolation for a device sharing the PCI bus. USB passthrough works at the USB protocol layer through QEMU's usb-host device or the LXC device layer, and doesn't need IOMMU at all.

Why does my device show up in lsusb but not in the GUI's USB device dropdown?
The GUI dropdown is populated by the same enumeration QEMU uses at VM start. If the device was plugged in after the Proxmox VE web service last refreshed its device list, a browser refresh usually fixes it; if not, confirm the device isn't already claimed by another VM's usbN entry or bound to a host kernel driver you don't expect.

Is there a limit to how many USB devices I can pass through to one VM?
Current QEMU machine types support up to 14 usbN slots per VM (usb0–usb13). In practice you're far more likely to run into physical USB controller bandwidth limits, especially if several passed-through devices share the same physical hub or root port.

Does USB passthrough work the same way for Windows and Linux guests?
Yes — from the VM's perspective, a passed-through USB device is indistinguishable from one plugged directly into physical hardware, so ordinary Windows or Linux drivers for that device apply normally. No guest-side Proxmox-specific driver is needed for USB, unlike some GPU passthrough scenarios that require guest tools for full functionality.

Can I use Resource Mapping for a device that only exists on one node?
Yes — a mapping can have entries for just a subset of cluster nodes. The VM will only start successfully on a node where the mapping resolves to an actual device; on other nodes, Proxmox will refuse to start it rather than silently ignoring the passthrough request, which is the correct failure mode for hardware-bound devices.

Conclusion

USB passthrough on Proxmox VE trades the complexity of PCI/GPU passthrough for a much shorter list of concerns: pick ID-based or port-based binding depending on whether you have duplicate hardware, remember that guests need a full restart (not just a reboot) to pick up changes, and use Resource Mappings the moment more than one node in your cluster might run the VM. For containers, the PVE 8.0+ device-passthrough feature via pct set --devN is worth adopting outright — it removes an entire class of unprivileged-container permission bugs that used to make manual lxc.mount.entry configuration a recurring source of forum threads. Once a mapping or a usbN entry is in place, the device behaves exactly as if it were plugged into the guest directly, with no ongoing maintenance beyond what you'd do for physical hardware anyway.