Install & Compatibility
Where this runs
tested against v2.4.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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 23.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.5s · import 0.000s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BluetoothAdapters
✓ from bluetooth_adapters import BluetoothAdapters
✗ from bluetooth_adapters import get_adapter_manager
AdapterDetails
✓ from bluetooth_adapters import AdapterDetails
AdvertisementHistory
✓ from bluetooth_adapters import AdvertisementHistory
This quickstart demonstrates how to asynchronously retrieve and print information about available Bluetooth adapters on the system. It uses `get_adapter_manager` to get the system's adapter manager and then fetches all detected adapters.
import asyncio
from bluetooth_adapters import get_adapter_manager
async def main():
manager = await get_adapter_manager()
adapters = await manager.adapters()
if not adapters:
print("No Bluetooth adapters found.")
return
print(f"Found {len(adapters)} Bluetooth adapter(s):")
for adapter in adapters:
print(f"- Adapter: {adapter.name} ({adapter.address}) "
f"Powered: {adapter.powered} Discovering: {adapter.discovering}")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingMajor versions of the underlying `bleak` library (e.g., 2.x, 3.x) can introduce breaking changes in behavior or API. `bluetooth-adapters` version 2.1.1 explicitly supports `bleak` 1.x. Users integrating with newer `bleak` versions might encounter compatibility issues or require an updated `bluetooth-adapters` release.fixCheck the `bluetooth-adapters` PyPI page or GitHub releases for updates that explicitly support newer `bleak` major versions. Ensure your installed `bleak` version aligns with the requirements of your `bluetooth-adapters` version.
affects: All versions where `bleak` dependency is not updated to match current `bleak` major versions (e.g., `bluetooth-adapters` < 2.2.0 with `bleak` >= 2.0.0).
gotchaOn Linux, `bluetooth-adapters` relies on the BlueZ service and D-Bus. Issues can arise if D-Bus is not running, if the BlueZ service is not active, or due to incorrect D-Bus permissions, leading to adapter enumeration failures or communication problems.fixEnsure the BlueZ service is running and D-Bus is properly configured. Check system logs for D-Bus or BlueZ errors. You might need to adjust user permissions to interact with Bluetooth devices via D-Bus.
affects: All versions on Linux.
gotchaBluetooth performance (range, stability, audio quality) can be significantly impacted by electromagnetic interference, particularly from USB 3.0 ports. Plugging a Bluetooth adapter into a USB 3.0 port can cause poor signal quality due to interference in the 2.4GHz band.fixPlug Bluetooth adapters into a USB 2.0 port. If only USB 3.0 ports are available, use a USB 2.0 extension cable to move the adapter away from the computer or other potential sources of interference.
affects: All versions (hardware-level issue).
deprecatedVersions of `bluetooth-adapters` prior to 2.1.0 had a bug that could prevent D-Bus connections from being properly closed, potentially leading to resource leaks or stale connections over time.fixUpgrade to `bluetooth-adapters` version 2.1.0 or newer to ensure D-Bus connections are reliably closed.
affects: < 2.1.0
Upgrade
Version history
2.4.0latest on PyPI · released May 26, 2026
Audit
Dependencies
bleakrequiredCore dependency for asynchronous Bluetooth Low Energy (BLE) communication. The library abstracts platform-specific BLE backends like BlueZ (Linux), Core Bluetooth (macOS), and Windows.
dbus-fastrequiredUsed for D-Bus communication on Linux systems, which is essential for interacting with the BlueZ Bluetooth stack.