{"id":5988,"library":"libusb1","title":"libusb1","description":"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.","status":"active","version":"3.3.1","language":"en","source_language":"en","source_url":"https://github.com/vpelletier/python-libusb1","tags":["usb","hardware","low-level","ctypes","libusb"],"install":[{"cmd":"pip install libusb1","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This Python library is a ctypes-based wrapper for the `libusb-1.0` C library. While Windows wheels bundle the `libusb-1.0` DLL, the underlying C library must be installed on other operating systems (e.g., via system package managers like `apt`, `brew`, etc.).","package":"libusb-1.0 (C library)","optional":false}],"imports":[{"note":"The top-level `libusb1` module import is deprecated; all intended functionalities are exposed via the `usb1` module.","wrong":"import libusb1\n# ... libusb1.USBContext()","symbol":"USBContext","correct":"import usb1\n# ... then use usb1.USBContext()"}],"quickstart":{"code":"import usb1\nimport os\n\n# Replace with your device's Vendor ID and Product ID\n# You can often find these using 'lsusb' on Linux or device manager on Windows.\nVENDOR_ID = os.environ.get('USB_DEVICE_VENDOR_ID', '0x1234') # Example vendor ID\nPRODUCT_ID = os.environ.get('USB_DEVICE_PRODUCT_ID', '0x5678') # Example product ID\n\ndef list_all_devices():\n    with usb1.USBContext() as context:\n        print(\"Listing all USB devices:\")\n        for device in context.get  DeviceIterator():\n            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'}\")\n\ndef find_and_access_device(vendor_id, product_id):\n    print(f\"\\nAttempting to find device with ID {int(vendor_id, 16):04x}:{int(product_id, 16):04x}\")\n    try:\n        with usb1.USBContext() as context:\n            handle = context.openByVendorIDAndProductID(\n                int(vendor_id, 16),\n                int(product_id, 16),\n                skip_on_error=True,\n            )\n            if handle is None:\n                print(\"Device not found or access denied.\")\n                return\n\n            with handle.claimInterface(0): # Claim interface 0 (adjust as needed)\n                print(f\"Successfully found and claimed interface 0 of device {handle.getVendorID():04x}:{handle.getProductID():04x}\")\n                # Example: Read from an endpoint (replace ENDPOINT_ADDRESS and BUFFER_SIZE)\n                # data = handle.bulkRead(0x81, 64) \n                # print(f\"Read: {data.hex()}\")\n                # Example: Write to an endpoint\n                # handle.bulkWrite(0x01, b'Hello USB')\n\n    except usb1.USBError as e:\n        print(f\"USB Error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    list_all_devices()\n    find_and_access_device(VENDOR_ID, PRODUCT_ID)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Python 2.x support was dropped in `libusb1` version 3.0.0. Applications targeting Python versions older than 3.6 will not be compatible.","severity":"breaking","affected_versions":"< 3.0.0"},{"fix":"Change your imports from `import libusb1` to `import usb1`.","message":"Direct import from the `libusb1` module (e.g., `import libusb1`) is deprecated. All primary classes, functions, and constants are exposed through the `usb1` module.","severity":"deprecated","affected_versions":"All versions, explicitly warned since 1.6+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Upgrade to `libusb1` version 3.3.0 or newer to benefit from fixes addressing these finalizer issues.","message":"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.","severity":"gotcha","affected_versions":"< 3.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions on macOS with older Python/system setups"},{"fix":"Run your Python script with `sudo` on Linux, or configure proper udev rules to grant non-root users access to specific USB devices.","message":"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.","severity":"gotcha","affected_versions":"All versions on Linux/macOS"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}