ModuleNotFoundError после установки hidapi: правильный импорт в Python

Установили hidapi на Windows 11 и получили ModuleNotFoundError? Причина в имени модуля: используйте import hid. Есть пример кода и проверка через python -m pip.

Когда пакет устанавливается без ошибок, но при импорте всё рушится с ModuleNotFoundError, кажется, будто инструментам выбили почву из-под ног. Ниже — короткий разбор реального случая в Windows 11 с Python 3.12.6: установка hidapi через pip прошла успешно, но import hidapi падал во время выполнения. В итоге проблема оказалась не в установке, а в имени модуля для импорта.

Проблема: установлено, но импорт не работает

Приложение должно найти конкретное USB HID‑устройство по vendor_id и product_id, а затем прочитать полезную нагрузку. Код ниже демонстрирует задуманный сценарий и вызывает ошибку на этапе импорта.

import hidapi
# поиск целевого HID-устройства
all_nodes = hidapi.DeviceManager().devices()
for node in all_nodes:
    if node.vendor_id == 0x2341 and node.product_id == 0x0042:
        pad_handle = node
        break
# читаем и выводим 64 байта
payload = pad_handle.read(64)
print(payload)

Установка прошла нормально, но интерпретатор не находит модуль:

pip3 install hidapi
Successfully installed hidapi-0.14.0.post4
python -u "C:\Users\...\HID_test.py"
Traceback (most recent call last):
  File "C:\Users\...\HID_test.py", line 1, in <module>
    import hidapi
ModuleNotFoundError: No module named 'hidapi'

Что на самом деле происходит

Импортируемое имя, которое предоставляет установленный пакет, — hid, а не hidapi. В примере проекта показано использование import hid, что соответствует рабочему API. Этот подход видно в примере проекта: https://github.com/trezor/cython-hidapi/blob/master/try.py. Документация доступна здесь: https://github.com/trezor/cython-hidapi/blob/master/docs/.

Решение: импортируйте правильное имя модуля

Замените импорт на hid и оставьте остальную логику без изменений. Код по‑прежнему перечисляет устройства, проверяет vendor_id и product_id, читает 64 байта и выводит буфер.

import hid
dev_catalog = hid.DeviceManager().devices()
for item in dev_catalog:
    if item.vendor_id == 0x2341 and item.product_id == 0x0042:
        controller = item
        break
chunk = controller.read(64)
print(chunk)

Если после замены импорт всё ещё не работает, убедитесь, что пакет установлен именно в тот интерпретатор, которым вы запускаете скрипт. Надёжный способ — запускать pip через интерпретатор явно и затем выполнять код этим же интерпретатором:

python -m pip install hidapi
python -u "C:\path\to\HID_test.py"

Почему это важно

Имена пакетов и имена импортируемых модулей совпадают не всегда. В повседневной работе на Python эту несостыковку легко упустить из виду, особенно когда переключаешься между библиотеками с похожими названиями или биндингами. Осознание этого паттерна помогает не гоняться за мифическими проблемами окружения и сокращает путь от установки до рабочего кода. Это также напоминание: согласовывайте интерпретатор, в который ставит pip, с тем, который запускает программу — так вы избежите тонких сценариев «в одном терминале работает, в другом — нет».

Итоги

Если вы устанавливаете hidapi в Windows 11 с Python 3.12.6 и получаете ModuleNotFoundError при импорте hidapi, замените импорт на hid. Если проблемы не исчезли, устанавливайте через python -m pip и запускайте скрипт тем же python. В случае сомнений загляните в примеры и документацию проекта, чтобы подтвердить корректный путь импорта и доступный API. Такие небольшие различия в именах встречаются часто, и чем раньше их заметить, тем меньше времени вы потеряете.