libusb1

library3.4.0pypypi✓ verified 86d ago

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.

http-networking

pip install libusb1

github ↗package ↗

INSTALL

IMPORT

SIG · LIBUSB1

libusb1

http-networkingpythonv3.4.0

Install

1.6s avg

Import

78ms

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 v3.4.0 · 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.920 runs

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

glibc

py 3.10–3.920 runs

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

16MB installed

● package 16MB

Code

Verified usage

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

USBContext

✓ import usb1 # ... then use usb1.USBContext()

✗ import libusb1 # ... libusb1.USBContext()

The top-level `libusb1` module import is deprecated; all intended functionalities are exposed via the `usb1` module.

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)

Debug

Known issues

breakingPython 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.

affects: < 3.0.0

deprecatedDirect 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`.

affects: All versions, explicitly warned since 1.6+

gotchaOn 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.

affects: All versions on Windows

gotchaOlder 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.

affects: < 3.3.0

gotchaOn 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.

affects: All versions on macOS with older Python/system setups

gotchaApplications 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.

affects: All versions on Linux/macOS

Errors

Common errors & fixes

usb.core.NoBackendError: No backend available

The `libusb1` Python wrapper cannot find or load the underlying `libusb-1.0` shared library (e.g., `libusb-1.0.dll` on Windows, `libusb-1.0.so.0` on Linux, or `libusb-1.0.dylib` on macOS). This often happens due to missing installation of `libusb-1.0` itself, incorrect system PATH configuration, or issues with PyInstaller builds not bundling the DLL.

fix

1. **Install `libusb-1.0`:** On Windows, use Zadig to install a WinUSB, libusb-win32, or libusbk driver for your device. For other OSes, install via your package manager (e.g., `sudo apt install libusb-1.0-0` on Debian/Ubuntu, `brew install libusb` on macOS, `pacman -S libusb` on Arch Linux). 2. **Ensure `libusb1` is installed:** `pip install libusb1`. 3. **For PyUSB users (often seen with this error):** Manually specify the backend or ensure `libusb-1.0.dll` is in a discoverable location (e.g., `C:\Windows\System32` or the script's directory for Windows). Example of manual backend: `import usb.core; import usb.backend.libusb1; backend = usb.backend.libusb1.get_backend(find_library=lambda x: "C:\\path\\to\\libusb-1.0.dll")`.

usb1.USBError: [-4] LIBUSB_ERROR_NO_DEVICE

This error occurs when the specified USB device (e.g., by Vendor ID and Product ID) is not found, has been disconnected, or the application lacks the necessary permissions to detect or access it.

fix

1. Verify the device is connected and powered on. 2. Double-check the Vendor ID and Product ID used in your code. 3. On Linux, ensure appropriate udev rules are in place to grant your user access to USB devices (e.g., `SUBSYSTEM=="usb", ATTRS{idVendor}=="YOUR_VENDOR_ID", ATTRS{idProduct}=="YOUR_PRODUCT_ID", MODE="0666", GROUP="plugdev"`). 4. On Windows, ensure the correct libusb-compatible driver (e.g., WinUSB) is installed for the device using a tool like Zadig.

usb1.USBError: [-3] LIBUSB_ERROR_ACCESS

The application does not have sufficient permissions to open or interact with the USB device, even if the device is present and drivers are installed. This is common on Linux systems.

fix

On Linux, configure udev rules to grant your user access to the USB device. Create a file like `/etc/udev/rules.d/99-usb-device.rules` with content: `SUBSYSTEM=="usb", ATTRS{idVendor}=="YOUR_VENDOR_ID", ATTRS{idProduct}=="YOUR_PRODUCT_ID", MODE="0666", GROUP="plugdev"`. Replace `YOUR_VENDOR_ID` and `YOUR_PRODUCT_ID` with the actual values. Then, reload udev rules with `sudo udevadm control --reload-rules && sudo udevadm trigger`, and potentially add your user to the `plugdev` group (`sudo usermod -aG plugdev $USER`). Restart your system or log out/in for changes to take effect. Running the script with `sudo` might temporarily bypass this but is not a recommended long-term solution.

usb1.USBErrorNotSupported: LIBUSB_ERROR_NOT_SUPPORTED [-12]

This error indicates that an attempted operation (e.g., claiming an interface, specific transfer type) is not supported by the underlying `libusb-1.0` library on the current platform, or more commonly, the installed USB driver for the device is not compatible with libusb (e.g., a generic Windows driver instead of WinUSB).

fix

On Windows, this usually means the device is using a default or proprietary driver that doesn't expose the necessary functionality through the `libusb-1.0` API. Use Zadig to install a libusb-compatible driver (like WinUSB, libusb-win32, or libusbk) for your specific USB device. Be aware that changing the driver might affect other software that expects the original driver.

Upgrade

Version history

3.4.0latest on PyPI · released May 16, 2026

Audit

Dependencies

libusb-1.0 (C library)requiredThis 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.).

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/vpelletier/python-libusb1 ↗

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