pyusb

library1.3.1pypypi✓ verified 26d ago

PyUSB provides easy USB access for Python, abstracting away the low-level details of USB communication. It allows Python applications to interact with USB devices on various operating systems. The current version is 1.3.1, and it receives updates to fix bugs and maintain compatibility, though releases are not on a fixed schedule.

http-networking devops testing serialization data

pip install pyusb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PYUSB

pyusb

http-networkingpythonv1.3.1

Install

1.6s avg

Import

25ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.028s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.022s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

core

✓ import usb.core

util

✓ import usb.util

backend

✓ import usb.backend.libusb1 as libusb1

Commonly aliased for convenience when selecting specific backends.

This quickstart demonstrates how to find an attached USB device, retrieve its manufacturer and product strings, and properly dispose of resources. Replace `dev = usb.core.find()` with specific `idVendor` and `idProduct` for a targeted search.

import usb.core import usb.util # Find the first USB device available. # For a real application, you'd specify idVendor and idProduct, e.g., # dev = usb.core.find(idVendor=0x046d, idProduct=0xc077) # Example: Logitech mouse dev = usb.core.find() # Finds any device if dev is None: print("No USB device found. Ensure a device is connected and permissions are set.") else: print(f"Device found: Bus {dev.bus}, Address {dev.address}") try: # Try to get manufacturer and product strings # These indices (iManufacturer, iProduct) might be 0 or invalid on some devices manufacturer = usb.util.get_string(dev, dev.iManufacturer) product = usb.util.get_string(dev, dev.iProduct) print(f" Manufacturer: {manufacturer}") print(f" Product: {product}") except Exception as e: print(f" Could not read device strings (permissions or device issue): {e}") # Always remember to dispose resources when done with the device usb.util.dispose_resources(dev) print("Resources disposed.")

Debug

Known issues

gotchaPyUSB is a wrapper around a low-level USB library (e.g., libusb-1.0), which must be installed separately on your system. PyUSB will not function without a compatible backend.

fix

Install `libusb-1.0` on your operating system. For example:
- Debian/Ubuntu: `sudo apt-get install libusb-1.0-0-dev`
- macOS (Homebrew): `brew install libusb`
- Windows: Download binaries from the libusb website and ensure they are in your system's PATH or explicitly specified using `usb.backend.libusb1.get_backend()`.

affects: All

gotchaOn Linux, accessing USB devices often requires root privileges or specific udev rules to grant non-root users access. Without correct permissions, `usb.core.find()` will fail to locate devices.

fix

Run your Python script as root (`sudo python your_script.py`) or, for a more secure approach, create a udev rule (e.g., `/etc/udev/rules.d/99-mydevice.rules`) that grants access to specific devices and add your user to the relevant group. Example rule: `SUBSYSTEM=="usb", ATTR{idVendor}=="<vendor_id>", ATTR{idProduct}=="<product_id>", MODE="0666", GROUP="plugdev"`.

affects: All

breakingAs of PyUSB 1.3.0, the minimum required Python version is 3.9. Attempting to install or run PyUSB 1.3.0+ on older Python versions (e.g., 3.8, 3.7, 3.6) will result in installation failures or runtime errors.

fix

Upgrade your Python environment to version 3.9 or newer. If you must use an older Python version, restrict your PyUSB dependency to `<1.3.0` (e.g., `pip install 'pyusb<1.3.0'`).

affects: >=1.3.0

breakingVersion 1.3.0 introduced a regression in `ctrl_transfer` where supplied read buffers were discarded, potentially leading to incorrect or unexpected behavior when pre-allocating buffers for control reads. This was fixed in 1.3.1.

fix

Upgrade to PyUSB 1.3.1 or newer to ensure `ctrl_transfer` correctly utilizes supplied read buffers. If stuck on 1.3.0, avoid pre-allocating read buffers for `ctrl_transfer` and rely on the function to return a newly allocated buffer.

affects: 1.3.0

gotchaThe hashability of `Device` objects was broken in PyUSB 1.2.0, making them unsuitable for use in sets or as dictionary keys. This was restored in 1.2.1. Additionally, `Device.__eq__()` was implemented in 1.2.0, changing how device objects are compared.

fix

If you rely on `Device` objects being hashable (e.g., storing them in sets or using them as dict keys), ensure you are on PyUSB 1.2.1 or newer. Be aware of the `__eq__` implementation changes when comparing device objects between 1.1.x and 1.2.x+.

affects: 1.2.0

Errors

Common errors & fixes

usb.core.NoBackendError: No backend available

PyUSB could not find a suitable USB backend library (like `libusb`) on your system.

fix

Install `libusb` on your operating system (e.g., `sudo apt install libusb-1.0-0-dev` on Linux, or use Zadig on Windows), and ensure its path is discoverable, or explicitly specify its location using `usb.backend.libusb1.get_backend(find_library=lambda x: "/path/to/libusb-1.0.so")`.

usb.core.USBError: [Errno 13] Access denied

The current user lacks the necessary permissions to open and communicate with the USB device.

fix

On Linux, create a udev rule for the device (e.g., `SUBSYSTEM=="usb", ATTR{idVendor}=="VVVV", ATTR{idProduct}=="PPPP", MODE="0666"`) and reload udev rules, or temporarily run your script with `sudo` (not recommended for production).

OSError: [WinError 126] The specified module could not be found

On Windows, PyUSB cannot find the `libusb-1.0.dll` file in the system's PATH or other standard locations required by its backend.

fix

Install `libusb` on Windows (e.g., using Zadig or MSYS2/MinGW), then ensure `libusb-1.0.dll` is in a directory listed in your system's PATH environment variable, or manually specify its path: `backend = usb.backend.libusb1.get_backend(find_library=lambda x: r'C:\Path\To\libusb-1.0.dll')`.

usb.core.USBError: [Errno 16] Device or resource busy

Another process or kernel driver on the operating system is currently holding the USB device, preventing PyUSB from accessing it.

fix

Ensure all other applications that might be using the device are closed, or on Linux, explicitly detach the kernel driver using `dev.detach_kernel_driver(interface_number)` before claiming the interface.

Upgrade

Version history

1.3.1latest on PyPI · released Jan 8, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/pyusb/pyusb ↗

packagehttps://pypi.org/project/pyusb/ ↗

homepagehttps://pyusb.github.io/pyusb ↗