libusb1

3.3.1 · active · verified Tue Apr 14

libusb1 is a pure-Python wrapper for the `libusb-1.0` C library, providing low-level access to USB devices. It exposes both synchronous and asynchronous APIs, allowing access to all USB transfer types (control, bulk, interrupt, isochronous). Unlike PyUSB, which aims for a common subset across various USB libraries, libusb1 focuses on making the entire `libusb-1.0` API available. The project is actively maintained, with regular releases addressing bug fixes and improvements, such as the recent 3.3.1 release.

Warnings

breaking Python 2.x support was dropped in `libusb1` version 3.0.0. Applications targeting Python versions older than 3.6 will not be compatible.
Fix: Upgrade your Python environment to 3.6 or newer. If you must use Python 2.x, use an older `libusb1` version (e.g., < 3.0.0) but be aware it will not receive updates or bug fixes.
deprecated Direct import from the `libusb1` module (e.g., `import libusb1`) is deprecated. All primary classes, functions, and constants are exposed through the `usb1` module.
Fix: Change your imports from `import libusb1` to `import usb1`.
gotcha On Windows, while `libusb1` wheels bundle the `libusb-1.0` DLL, you still need to install appropriate USB drivers (e.g., WinUSB or libusbK) for your specific USB devices. The Python library does not handle driver installation.
Fix: Use tools like Zadig (https://zadig.akeo.ie/) or provide a custom driver to install the correct backend driver for your USB device. Installing from source does *not* bundle the DLL either, requiring manual placement.
gotcha Older versions of `libusb1` (prior to 3.3.0) might have experienced 'finalizer registration errors,' which could manifest as warnings about USB devices being leaked or still referenced during application shutdown.
Fix: Upgrade to `libusb1` version 3.3.0 or newer to benefit from fixes addressing these finalizer issues.
gotcha On some macOS systems, the `select.poll` mechanism (used for asynchronous I/O) might be missing or have limitations, potentially affecting the reliability of asynchronous USB operations.
Fix: Check your system's `select.poll` support if encountering issues with asynchronous transfers on macOS. Consider alternative event handling or synchronous operations if `poll` is problematic.
gotcha Applications using `libusb1` (or `libusb-1.0` in general) often require elevated privileges (e.g., root or administrator) to access and interact with USB devices on the system, particularly on Linux.
Fix: Run your Python script with `sudo` on Linux, or configure proper udev rules to grant non-root users access to specific USB devices.

Install

pip install libusb1 Install with pip

Imports

USBContext
```
import usb1
# ... then use usb1.USBContext()
```
The top-level `libusb1` module import is deprecated; all intended functionalities are exposed via the `usb1` module.

Quickstart

This quickstart demonstrates how to initialize a USB context, list all connected USB devices, and then find and claim an interface on a specific device by its Vendor ID and Product ID. Remember to replace `VENDOR_ID` and `PRODUCT_ID` with the actual values for your target device, and adjust the interface number and endpoint operations as required. Root privileges may be necessary on some systems to access USB devices.

import usb1
import os

# Replace with your device's Vendor ID and Product ID
# You can often find these using 'lsusb' on Linux or device manager on Windows.
VENDOR_ID = os.environ.get('USB_DEVICE_VENDOR_ID', '0x1234') # Example vendor ID
PRODUCT_ID = os.environ.get('USB_DEVICE_PRODUCT_ID', '0x5678') # Example product ID

def list_all_devices():
    with usb1.USBContext() as context:
        print("Listing all USB devices:")
        for device in context.get  DeviceIterator():
            print(f"  Bus {device.getBusNumber():03d} Device {device.getDeviceAddress():03d}: ID {device.getVendorID():04x}:{device.getProductID():04x} {device.getManufacturerString() or 'N/A'} {device.getProductString() or 'N/A'}")

def find_and_access_device(vendor_id, product_id):
    print(f"\nAttempting to find device with ID {int(vendor_id, 16):04x}:{int(product_id, 16):04x}")
    try:
        with usb1.USBContext() as context:
            handle = context.openByVendorIDAndProductID(
                int(vendor_id, 16),
                int(product_id, 16),
                skip_on_error=True,
            )
            if handle is None:
                print("Device not found or access denied.")
                return

            with handle.claimInterface(0): # Claim interface 0 (adjust as needed)
                print(f"Successfully found and claimed interface 0 of device {handle.getVendorID():04x}:{handle.getProductID():04x}")
                # Example: Read from an endpoint (replace ENDPOINT_ADDRESS and BUFFER_SIZE)
                # data = handle.bulkRead(0x81, 64) 
                # print(f"Read: {data.hex()}")
                # Example: Write to an endpoint
                # handle.bulkWrite(0x01, b'Hello USB')

    except usb1.USBError as e:
        print(f"USB Error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    list_all_devices()
    find_and_access_device(VENDOR_ID, PRODUCT_ID)

view raw JSON →