# HIDAPI: a single C header over 4 platform backends for USB and Bluetooth HID devices

> HIDAPI is a C library that lets an application talk to USB and Bluetooth HID-class devices on Windows, Linux, FreeBSD and macOS through a single header, hiding 4 separate platform-specific backends. On Linux the backend is a link-time choice, and the hidraw option cannot reach keyboards or mice.

**libusb/hidapi** — A Simple cross-platform library for communicating with HID devices

- Repository: https://github.com/libusb/hidapi
- Website: https://libusb.info/hidapi/
- Stars: 2,273 · Forks: 477
- Language: C
- License: NOASSERTION
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/libusb-hidapi

## HIDAPI targets C applications that need USB and Bluetooth HID across all 4 major platforms

HID (Human Interface Device) is the USB class for devices like gamepads, sensors and custom hardware. Communicating with those devices at the application layer without HIDAPI means calling different platform-specific APIs on each OS: hid.dll on Windows, IOHidManager on macOS, hidraw ioctls on Linux. HIDAPI collapses those into a single C header, hidapi.h, with a consistent function set across all 4 platforms.

Originally written by Alan Ott at signal11, HIDAPI moved to the libusb/hidapi repository on June 4th, 2019, to merge important bugfixes and continue development.

Deployment options split into 2 paths. An application can link against a shared library (.so, .dll or .dylib) built from HIDAPI, or it can embed HIDAPI directly by adding 1 source file per platform and a single header. For targets without a package manager or with tight dependency rules, embedding avoids the shared library requirement entirely.

## On Linux, both backends are built by default but the application chooses one at link time

Linux is the only platform where HIDAPI offers 2 interchangeable backends. In linux/hid.c, hidraw uses the Linux kernel's hidraw interface and supports both USB and Bluetooth HID devices. In libusb/hid.c, the libusb backend bypasses the kernel driver and communicates directly over USB using libusb-1.0, which means Bluetooth devices are outside its scope.

Both backends are compiled by default, and the application picks between them at link time by linking against either libhidapi-hidraw or libhidapi-libusb. That decision is fixed when the binary is compiled; switching backends requires relinking.

For unprivileged access to HID devices, a udev rule file is required. HIDAPI ships an example at udev/69-hid.rules, and the README says this file must be installed alongside any application that uses the library. Without it, ordinary users cannot open HID devices.

## Installing the dev package on Ubuntu and calling hid_open for the first time

On Ubuntu, a single APT command installs the headers and shared libraries needed to build against HIDAPI.

```sh
sudo apt install libhidapi-dev
```

For other distributions, the README points to each package manager's own documentation for the correct package name.

Once installed, the core call sequence runs from hid_init through hid_open, device interaction, hid_close and hid_exit. Below is the skeleton from the README sample, which opens a device at VID 0x4d8 and PID 0x3f (a Microchip USB Generic HID reference device used only to illustrate the API).

```c
res = hid_init();
handle = hid_open(0x4d8, 0x3f, NULL);
if (!handle) {
    printf("Unable to open device\n");
    hid_exit();
    return 1;
}
hid_close(handle);
res = hid_exit();
```

BUILD.md in the repository root covers building from source. Separate BUILD.cmake.md and BUILD.autotools.md files address the cmake and autotools paths, and meson.build and CMakeLists.txt both appear at the root alongside configure.ac.

## Keyboards and mice are blacklisted from hidraw nodes by the Linux kernel

hidraw on Linux only works with devices that have a hidraw node in /dev. Keyboards, mice and some other devices are deliberately withheld from having hidraw nodes by the kernel. HIDAPI's README names this a blacklist and adds that for "nearly all the uses of hidraw, this is not a problem."

For most custom USB peripherals, measurement devices and game controllers, that is true. For a project that needs low-level access to a keyboard or a device the kernel treats as a standard input class, hidraw will not work.

Switching to the libusb backend bypasses the kernel driver and can reach those devices over USB, but Bluetooth access disappears. No single Linux backend covers both Bluetooth HID and kernel-blacklisted USB HID devices. A project with that combination must pick 1 backend, accept its restriction, or add platform-specific code alongside HIDAPI.

## hid_write at random can break devices, and the README sample removes error checking

Before the sample code, HIDAPI's README places a warning: "Only run the code you understand, and only when it conforms to the device spec. Writing data (hid_write) at random to your HID devices can break them." Devices with firmware update paths or configuration registers accessible as HID feature reports are at risk from malformed writes.

Adding to that, the sample code in the README removes all error handling and marks this explicitly: "(with error checking removed for simplicity)." Every function that returns int in the sample, hid_init, hid_write and hid_read, can return -1 on failure. Code copied from that sample without adding checks will silently swallow failures, including failed device opens.

For a starting point with more structure, the README points to hidtest/test.c in the repository.

## hidapitester handles console HID testing without compiling from the HIDAPI source tree

Before writing a custom application, confirming that a device responds to expected report IDs from the command line avoids wasted development cycles. HIDAPI ships a Test GUI under testgui/ that can serve that purpose, but building it requires Fox Toolkit v1.6. More to the point, the HIDAPI README states that this GUI "is not actively developed nor supported by HIDAPI team" and describes it as "a historical artifact" that will not receive new features or bugfixes.

For interactive device probing, HIDAPI's README points to hidapitester, a separate project by todbot on GitHub. hidapitester has a console interface for most of HIDAPI's features and can be run without touching the HIDAPI source tree at all.

Between these 2 options, the difference is dependency weight and maintenance status. Fox Toolkit GUI is bundled in testgui/ and can be compiled against Fox Toolkit v1.6, but the HIDAPI team officially considers it a historical artifact with no planned bug fixes or updates. hidapitester is external to the HIDAPI repository but is the path the current README recommends for pre-development device testing.

## cmake, autotools and meson are all documented separately, with 1 source file per platform for embedding

Alongside the single-file embedding path, HIDAPI supports 3 build systems. CMakeLists.txt, meson.build and configure.ac all appear at the repository root, with BUILD.md, BUILD.cmake.md and BUILD.autotools.md providing separate documentation for each. No preference among them is stated in the README.

For the embed path, BUILD.md contains remarks on adding HIDAPI directly into a source tree, covering what the README describes as a single source file per platform plus 1 header. This deployment is the one most useful for firmware or constrained-environment projects that cannot take a shared library as a runtime dependency.

The last push was on 2026-09-09; hidapi-0.15.0 (published 2025-05-18) is the most recent release, and the repository offers 3 licensing options documented in LICENSE.txt (BSD, GPL-3 and the original licence).

## Conclusion

HIDAPI is a practical choice when you need a single C API for USB HID devices across Windows, Linux, FreeBSD and macOS without writing 4 separate platform drivers. Avoid the hidraw backend on Linux if your target devices are keyboards or mice; use the libusb backend for USB-only access to those device classes. If Bluetooth HID support on Linux is required, the libusb backend will not serve you, and you will need the hidraw backend along with a kernel that meets the 2.6.39 requirement. Before shipping, install the udev/69-hid.rules file or unprivileged users will not be able to open any HID device.

## FAQ

### What is HIDAPI used for?

HIDAPI is a C library for communicating with USB and Bluetooth HID-class devices on Windows, Linux, FreeBSD and macOS. It provides a consistent API for sending and receiving input, output and feature reports without writing platform-specific code for each OS.

### How do I install HIDAPI on Linux?

On Ubuntu, run sudo apt install libhidapi-dev to install the development package. For other distributions, the README points to each package manager's documentation for the correct package name.

### What is the difference between the HIDAPI hidraw and libusb backends on Linux?

hidraw uses the kernel's hidraw interface and supports both USB and Bluetooth HID devices but requires kernel 2.6.39 or later and cannot reach keyboards or mice. libusb bypasses the kernel driver and works with a wider device range over USB, but does not support Bluetooth. The application picks between them at link time.

### Can HIDAPI communicate with keyboards and mice on Linux?

With the hidraw backend, keyboards and mice are blacklisted from hidraw nodes by the Linux kernel and are unreachable. The libusb backend can reach them over USB but not over Bluetooth.

### Does HIDAPI support Bluetooth HID devices?

On Windows and macOS, HIDAPI supports both USB and Bluetooth HID devices natively. On Linux, only the hidraw backend supports Bluetooth HID; the libusb backend covers USB only.

## Sources

- [Issues](https://github.com/libusb/hidapi/issues)
- [libusb/hidapi on GitHub](https://github.com/libusb/hidapi)
- [Project website](https://libusb.info/hidapi/)
- [README](https://github.com/libusb/hidapi/blob/master/README.md)
- [Releases](https://github.com/libusb/hidapi/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/libusb-hidapi