{"id":6551,"library":"bluetooth-adapters","title":"Bluetooth Adapters","description":"bluetooth-adapters is a Python library that provides tools to enumerate and find Bluetooth adapters on various operating systems. It is currently at version 2.1.1 and receives regular updates, typically every few months, addressing bugs and dependency updates.","status":"active","version":"2.1.1","language":"en","source_language":"en","source_url":"https://github.com/bluetooth-devices/bluetooth-adapters","tags":["bluetooth","hardware","adapters","enumeration","bleak","dbus"],"install":[{"cmd":"pip install bluetooth-adapters","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for asynchronous Bluetooth Low Energy (BLE) communication. The library abstracts platform-specific BLE backends like BlueZ (Linux), Core Bluetooth (macOS), and Windows.","package":"bleak"},{"reason":"Used for D-Bus communication on Linux systems, which is essential for interacting with the BlueZ Bluetooth stack.","package":"dbus-fast"}],"imports":[{"symbol":"get_adapter_manager","correct":"from bluetooth_adapters import get_adapter_manager"}],"quickstart":{"code":"import asyncio\nfrom bluetooth_adapters import get_adapter_manager\n\nasync def main():\n    manager = await get_adapter_manager()\n    adapters = await manager.adapters()\n    if not adapters:\n        print(\"No Bluetooth adapters found.\")\n        return\n\n    print(f\"Found {len(adapters)} Bluetooth adapter(s):\")\n    for adapter in adapters:\n        print(f\"- Adapter: {adapter.name} ({adapter.address}) \"\n              f\"Powered: {adapter.powered} Discovering: {adapter.discovering}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"fix":"Check 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.","message":"Major 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.","severity":"breaking","affected_versions":"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)."},{"fix":"Ensure 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.","message":"On 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.","severity":"gotcha","affected_versions":"All versions on Linux."},{"fix":"Plug 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.","message":"Bluetooth 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.","severity":"gotcha","affected_versions":"All versions (hardware-level issue)."},{"fix":"Upgrade to `bluetooth-adapters` version 2.1.0 or newer to ensure D-Bus connections are reliably closed.","message":"Versions 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.","severity":"deprecated","affected_versions":"< 2.1.0"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}