USB Devices

0.4.5 · active · verified Thu Apr 16

usb-devices is a Python library providing tools for mapping, describing, and resetting USB devices connected to the system. It offers a cross-platform API to enumerate devices and retrieve detailed information such as product, manufacturer, and serial numbers, and provides functionality to reset individual devices. The library is actively maintained, with version 0.4.5 being the latest, and sees frequent minor releases addressing compatibility and stability.

Common errors

```
ModuleNotFoundError: No module named 'usb_devices'
```
cause The `usb-devices` package is not installed in your Python environment or is not accessible via the Python path.

fix Install the package using pip: `pip install usb-devices`
```
FileNotFoundError: [Errno 2] No such file or directory: '/sys/bus/usb/devices/...' (or similar path)
```
cause The library could not find the expected system files for enumerating USB devices. This typically happens on Linux if `/sys/bus/usb/devices` is not mounted or accessible, or if the system uses an unusual file structure.

fix Verify that your operating system's USB device file structure is intact and accessible. This might indicate an issue with the OS configuration or an unsupported environment.
```
Error: Operation not permitted
```
cause This error, often seen on Linux, indicates that the current user lacks the necessary permissions to perform the requested USB operation (e.g., accessing device information or resetting a device).

fix Run your script with `sudo` (e.g., `sudo python your_script.py`) or, for a more persistent solution, configure `udev` rules to grant your user access to USB devices. On Windows, ensure you are running as Administrator.

Warnings

gotcha Accessing USB devices often requires elevated permissions (e.g., root/administrator on Linux/Windows, or specific udev rules on Linux). Failure to do so will result in `Permission denied` errors, especially when attempting operations like `reset_device()`.
Fix: On Linux, configure udev rules (e.g., `sudo usermod -a -G dialout $USER`, then log out/in) or run the script with `sudo`. On Windows, ensure the script is run as Administrator.
gotcha Earlier versions (prior to v0.4.2) had known issues importing and running correctly on Windows. While fixed in v0.4.2+, specific Windows configurations or device drivers might still cause unexpected behavior or prevent device detection.
Fix: Ensure you are using `usb-devices` version 0.4.2 or newer. If issues persist, verify system drivers and run with administrative privileges.
gotcha Some USB devices may not provide complete `manufacturer` or `product` information. In such cases, these attributes on the `USBDevice` object will be `None`. Prior to v0.4.1, this could sometimes lead to errors if not explicitly handled.
Fix: Upgrade to `usb-devices` version 0.4.1 or newer. Always check for `None` when accessing `usb_device.manufacturer` or `usb_device.product` for robustness.
gotcha The `get_all_usb_devices()` method provides a snapshot of currently connected devices. It does not automatically update when devices are hot-plugged (connected or disconnected). To detect changes, you must call the method again.
Fix: If device presence changes are critical, re-call `USBDeviceInfo.get_all_usb_devices()` periodically or upon a trigger to refresh the device list.

Install

pip install usb-devices Install with pip

Imports

USBDeviceInfo
```
from usb_devices import USBDeviceInfo
```

Quickstart

This quickstart demonstrates how to discover and list all connected USB devices using `USBDeviceInfo.get_all_usb_devices()`. It prints key details for each device. Note that features like `reset_device()` typically require elevated permissions and are commented out for safe execution.

from usb_devices import USBDeviceInfo

print("Discovering USB devices...")

try:
    devices = USBDeviceInfo.get_all_usb_devices()
    if not devices:
        print("No USB devices found.")
    for usb_device in devices:
        print(f"Path: {usb_device.path}")
        print(f"Product: {usb_device.product}")
        print(f"Manufacturer: {usb_device.manufacturer}")
        print(f"Serial: {usb_device.serial_number}")
        print(f"VendorId: {usb_device.vendor_id}")
        print(f"ProductId: {usb_device.product_id}")
        print(f"Bus: {usb_device.bus_number}")
        print(f"Address: {usb_device.device_address}")
        print(f"Port: {usb_device.port_number}")
        # Example of resetting a device (requires permissions)
        # if "MyDevice" in str(usb_device.product):
        #     print(f"Attempting to reset {usb_device.product}...")
        #     usb_device.reset_device()
        #     print("Device reset.")
        print("-----------------------------------")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →