{"id":2250,"library":"pyusb","title":"PyUSB","description":"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.","status":"active","version":"1.3.1","language":"en","source_language":"en","source_url":"https://github.com/pyusb/pyusb","tags":["usb","hardware","device-control","low-level"],"install":[{"cmd":"pip install pyusb","lang":"bash","label":"Install PyUSB"}],"dependencies":[],"imports":[{"symbol":"core","correct":"import usb.core"},{"symbol":"util","correct":"import usb.util"},{"note":"Commonly aliased for convenience when selecting specific backends.","symbol":"backend","correct":"import usb.backend.libusb1 as libusb1"}],"quickstart":{"code":"import usb.core\nimport usb.util\n\n# Find the first USB device available. \n# For a real application, you'd specify idVendor and idProduct, e.g.,\n# dev = usb.core.find(idVendor=0x046d, idProduct=0xc077) # Example: Logitech mouse\n\ndev = usb.core.find() # Finds any device\n\nif dev is None:\n    print(\"No USB device found. Ensure a device is connected and permissions are set.\")\nelse:\n    print(f\"Device found: Bus {dev.bus}, Address {dev.address}\")\n    try:\n        # Try to get manufacturer and product strings\n        # These indices (iManufacturer, iProduct) might be 0 or invalid on some devices\n        manufacturer = usb.util.get_string(dev, dev.iManufacturer)\n        product = usb.util.get_string(dev, dev.iProduct)\n        print(f\"  Manufacturer: {manufacturer}\")\n        print(f\"  Product: {product}\")\n    except Exception as e:\n        print(f\"  Could not read device strings (permissions or device issue): {e}\")\n\n    # Always remember to dispose resources when done with the device\n    usb.util.dispose_resources(dev)\n    print(\"Resources disposed.\")","lang":"python","description":"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."},"warnings":[{"fix":"Install `libusb-1.0` on your operating system. For example:\n- Debian/Ubuntu: `sudo apt-get install libusb-1.0-0-dev`\n- macOS (Homebrew): `brew install libusb`\n- 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()`.","message":"PyUSB 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.","severity":"gotcha","affected_versions":"All"},{"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\"`.","message":"On 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.","severity":"gotcha","affected_versions":"All"},{"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'`).","message":"As 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.","severity":"breaking","affected_versions":">=1.3.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":"1.3.0"},{"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+.","message":"The 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.","severity":"gotcha","affected_versions":"1.2.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}