Registry / http-networking / hidapi

hidapi

JSON →
library0.15.0pypypi✓ verified 21d ago

hidapi is a Python library providing a Cython interface to the native HIDAPI library, enabling cross-platform communication with USB Human Interface Devices (HID). It works on Linux, Windows, and macOS. The current version is 0.15.0, with regular updates typically following the underlying HIDAPI C library.

pip install hidapi
INSTALL
IMPORT
SIG · HIDAPI
H
hidapi
http-networkingpythonv0.15.0
Install
1.6s avg
Import
10ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.5MB
glibc
py 3.103.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.
fix
On 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`.
fix
Run 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.
fix
Consult 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.
fix
Install 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.
fix
Install 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.
fix
On 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.
fix
Install 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.
Agent activity
56 hits · last 30 days
node
54
OpenAI (training)
1
Resources
hidapi — pip install hidapi · libregistry