habluetooth

library6.26.7pypypi✓ verified 21d ago

habluetooth is a Python library providing high-availability Bluetooth scanning and device management, built on top of Bleak. It aims to offer robust Bluetooth integration, often used in home automation contexts. The current version is 6.0.0. The project maintains an active and frequent release cadence, often with multiple updates per month, incorporating new features and bug fixes.

communication devops

pip install habluetooth

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · HABLUETOOTH

habluetooth

communicationpythonv6.26.7

Install

7.6s avg

Import

483ms

Disk

40MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.4.2 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.402s · 52.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 7.6s · import 0.370s · 50MB

40MB installed

● package 40MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BluetoothManager

✓ from habluetooth import BluetoothManager

HaBleakScannerWrapper

✓ from habluetooth import HaBleakScannerWrapper

✗ from habluetooth.scanner import HaBleakScannerWrapper

While 'from habluetooth.scanner import HaBleakScannerWrapper' works, the class is re-exported at the top-level for convenience.

This quickstart demonstrates how to initialize the `BluetoothManager`, set up a `HaBleakScannerWrapper`, and asynchronously iterate over discovered Bluetooth devices and their advertisement data. Run this script to see local Bluetooth devices and their basic information.

import asyncio from habluetooth import BluetoothManager, HaBleakScannerWrapper async def main(): manager = BluetoothManager() await manager.async_setup() scanner = HaBleakScannerWrapper(manager) print("Starting Bluetooth scan...") async with scanner: # Iterate over discovered devices and their advertisement data async for device, advertisement_data in scanner.advertisement_data: print(f"Device: {device.name or device.address}, RSSI: {advertisement_data.rssi}, Services: {advertisement_data.service_uuids}") # Uncomment the line below to stop after the first detected device # break await manager.async_stop() if __name__ == "__main__": try: asyncio.run(main()) except KeyboardInterrupt: print("Scan interrupted by user.")

Debug

Known issues

breakingVersion 6.0.0 removes `BaseBleakScanner` inheritance from `HaBleakScannerWrapper` and the `register_detection_callback` method. Code relying on these old Bleak patterns will no longer work.

fix

Update `HaBleakScannerWrapper` usage to leverage the new async iterator patterns (e.g., `scanner.advertisement_data`) or `discovered_devices_and_advertisement_data` methods, as demonstrated in the quickstart. Direct callback registration is no longer supported.

affects: >=6.0.0

gotchaThe `habluetooth` library requires Python 3.11 or newer. Installations or attempts to run on older Python versions will fail or result in compatibility errors.

fix

Ensure your development and deployment environments are running Python 3.11 or a more recent version. Consider using virtual environments to manage Python versions effectively.

affects: all

gotchahabluetooth maintains a rapid release cadence, often publishing multiple versions within a month. While this indicates active development, it means minor API adjustments or bug fixes can land frequently.

fix

For production or stable environments, consider pinning the `habluetooth` version in your `requirements.txt` to a specific minor version (e.g., `habluetooth~=6.0`) to avoid unexpected changes from newer releases. Regularly review the GitHub release notes before updating.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'habluetooth'

The `habluetooth` library is not installed in the Python environment you are currently using.

fix

Install the library using pip: `pip install habluetooth`.

AttributeError: 'HaBleakScannerWrapper' object has no attribute 'register_detection_callback'

This error occurs in `habluetooth` version 6.0.0 due to a breaking API change where the `register_detection_callback` method was removed from `HaBleakScannerWrapper`.

fix

Update your code to use the new async iterator patterns for scanning, such as `scanner.advertisement_data` or `discovered_devices_and_advertisement_data` methods, as direct callback registration is no longer supported.

habluetooth requires Python 3.11 or newer

The `habluetooth` library, particularly version 6.0.0, mandates Python 3.11 or a more recent version for compatibility.

fix

Ensure your Python development and deployment environments are running Python 3.11 or newer. Consider using virtual environments to manage Python versions effectively.

KeyError: '__reduce_cython__'

This specific error often arises during the loading of the Bluetooth integration (which uses `habluetooth`) in environments like Home Assistant, frequently due to cached bytecode inconsistencies or environment issues after updates.

fix

To resolve this, remove the Bluetooth adapter from your integration (e.g., in Home Assistant), reboot your system, and then add the Bluetooth device as a newly discovered integration.

Upgrade

Version history

6.26.7latest on PyPI · released Aug 19, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

26 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bluetooth-devices/habluetooth ↗

packagehttps://pypi.org/project/habluetooth/ ↗

docshttps://habluetooth.readthedocs.io ↗

changeloghttps://github.com/bluetooth-devices/habluetooth/blob/main/CHANGELOG.md ↗