Install & Compatibility
Where this runs
tested against v0.15.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.002s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
hid
✓ import hid
✗ import hidapi
The PyPI package is 'hidapi', but the import module name is 'hid'.
device
✓ h = hid.device()
Instantiate the device object directly from the 'hid' module.
This quickstart enumerates all connected HID devices, then attempts to connect to a specified device (using environment variables for Vendor ID and Product ID, or placeholders if not set). It demonstrates enabling non-blocking mode, writing data, and reading data from the device. Users should replace `VENDOR_ID` and `PRODUCT_ID` with their specific device's identifiers and adjust `data_to_write` and read sizes according to their device's HID report descriptor.
import hid
import os
import time
# --- Enumerate devices (useful for finding VID/PID) ---
print('Enumerating HID devices:')
for device_dict in hid.enumerate():
print('---')
for key, value in device_dict.items():
print(f'{key}: {value}')
print('---\n')
# --- Connect, read, and write (example with placeholder VID/PID) ---
# Replace with your device's Vendor ID and Product ID.
# On Linux, you may need appropriate udev rules or root privileges.
# On Windows, you might need hidapi.dll in your PATH.
VENDOR_ID = int(os.environ.get('HIDAPI_VENDOR_ID', '0x0000'), 16) # Example: 0x534C for Trezor
PRODUCT_ID = int(os.environ.get('HIDAPI_PRODUCT_ID', '0x0000'), 16) # Example: 0x0001 for Trezor One
if VENDOR_ID == 0x0000 or PRODUCT_ID == 0x0000:
print('Warning: Please set HIDAPI_VENDOR_ID and HIDAPI_PRODUCT_ID environment variables for a real test.')
print('Falling back to placeholder values; device opening may fail.')
try:
print(f'Attempting to open device VID: {hex(VENDOR_ID)}, PID: {hex(PRODUCT_ID)}')
h = hid.device()
h.open(VENDOR_ID, PRODUCT_ID)
print(f'Manufacturer: {h.get_manufacturer_string()}')
print(f'Product: {h.get_product_string()}')
print(f'Serial No: {h.get_serial_number_string()}')
h.set_nonblocking(1) # Enable non-blocking mode
# Example: Write some data (replace with actual device commands)
print('Writing example data...')
# Ensure data length matches device report size, padded with zeros if needed.
# The first byte might be a Report ID, or 0 if not used by the device.
data_to_write = [0, 63, 35, 35] + [0] * 60 # Example 64-byte report
h.write(data_to_write)
time.sleep(0.05)
# Example: Read data
print('Reading data...')
read_data = []
while True:
d = h.read(64) # Read up to 64 bytes
if d:
read_data.extend(d)
else:
break
if read_data:
print(f'Read data: {read_data}')
else:
print('No data read.')
print('Closing the device.')
h.close()
except IOError as ex:
print(f'Error opening or communicating with device: {ex}')
print('Ensure the device is connected and permissions are correct.')
except Exception as e:
print(f'An unexpected error occurred: {e}')
Debug
Known issues
gotchaThe `hidapi` Python package requires the underlying native `hidapi` library to be installed on your system. `pip install hidapi` only installs the Python bindings, not the C library itself. Users often encounter `IOError` or `OSError` if the native library is missing or improperly configured.fixOn Linux (Debian/Ubuntu), install `libusb-1.0-0-dev` and `libudev-dev` (or `libhidapi-hidraw0`/`libhidapi-libusb0`). On macOS, install `hidapi` via Homebrew (`brew install hidapi`). On Windows, ensure `hidapi.dll` is in a directory listed in your system's PATH, or beside your executable. The specific `hidapi.dll` might need to match your Python's architecture (32-bit vs 64-bit).
affects: All versions
gotchaOn Linux, accessing HID devices typically requires special permissions. Without them, `hid.open()` calls will fail with `IOError`.fixRun your Python script with `sudo` (not recommended for production). A better solution is to create a udev rule file (`.rules` in `/etc/udev/rules.d/`) to grant appropriate access to your user or a specific group for the target device's Vendor/Product ID. Remember to reload udev rules (`sudo udevadm control --reload-rules && sudo udevadm trigger`) and potentially replug the device.
affects: All versions on Linux
gotchaWhen reading or writing HID reports, the first byte often represents the 'Report ID'. If your device uses numbered reports, this byte will be the Report ID. If not, it's typically `0x00`. Misinterpreting this can lead to incorrect data parsing or writing issues.fixConsult your device's HID Report Descriptor to understand whether it uses numbered reports and what the expected report structure is. Adjust your `read()` and `write()` calls to account for the Report ID byte if present.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hid'
The Python `hidapi` wrapper library, which provides the `hid` module, is not installed in the active Python environment.
fixInstall the `hidapi` Python package using pip: `pip install hidapi`
ImportError: Unable to load any of the following libraries:libhidapi-hidraw.so libhidapi-libusb.so hidapi.dll
The Python `hidapi` wrapper cannot find the underlying native HIDAPI C library (e.g., `.so` on Linux, `.dll` on Windows, `.dylib` on macOS) in the system's library search paths.
fixInstall the native HIDAPI library using your system's package manager (e.g., `sudo apt install libhidapi-hidraw0` or `sudo brew install hidapi`). On Windows, ensure `hidapi.dll` is in a directory included in your system's PATH environment variable, or manually load it using `ctypes.CDLL()` before importing `hid`.
hidapi: failed to open device
This error typically indicates that the current user lacks the necessary permissions to access the USB HID device, especially on Linux, or insufficient privileges on Windows.
fixOn Linux, create a udev rule for your device's Vendor ID (VID) and Product ID (PID) to grant read/write permissions (e.g., `KERNEL=="hidraw*", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0666"`) in `/etc/udev/rules.d/`, then reload udev rules with `sudo udevadm control --reload-rules && sudo udevadm trigger` and replug the device. On Windows, try running the application as an administrator. ERROR: Failed building wheel for hidapi ... error: Microsoft Visual C++ 14.0 or greater is required.
During `pip install hidapi` on Windows, if a pre-compiled wheel is not available, pip attempts to build from source, which requires the Microsoft Visual C++ Build Tools.
fixInstall the 'Microsoft C++ Build Tools' which are available as part of Visual Studio Build Tools from Microsoft's website.
Upgrade
Version history
0.15.0latest on PyPI · released Dec 9, 2025
Audit
Dependencies
CythonoptionalRequired for building the Cython extensions if installing from source or if pre-built wheels are not available.
libusbrequiredNative HIDAPI library backend (often provided by system packages like libusb-1.0-0-dev on Linux, or Homebrew hidapi on macOS). Essential for device communication.
libudevrequiredSystem dependency on Linux for device discovery and access (e.g., libudev-dev on Debian/Ubuntu).
hidraw (Linux kernel module)requiredAlternative Linux backend to libusb. The cython-hidapi library defaults to hidraw where available.