{"id":24299,"library":"pybluez","title":"PyBluez","description":"PyBluez is a Python extension module that enables access to system Bluetooth resources. It provides a socket-based interface similar to the standard Python socket module, supporting Bluetooth RFCOMM, L2CAP, and other protocols. Currently at version 0.23, it is primarily for Linux and Windows, with limited macOS support. The project is in maintenance mode with infrequent releases.","status":"maintenance","version":"0.23","language":"python","source_language":"en","source_url":"https://github.com/pybluez/pybluez","tags":["bluetooth","rfcomm","l2cap","legacy"],"install":[{"cmd":"pip install pybluez","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"On Windows, the PyBluez installer may require Visual C++ Redistributable; on Linux, bluez and libbluetooth-dev are system dependencies.","package":"PyBluez","optional":false}],"imports":[{"note":"The main module is named 'bluetooth', not 'pybluez'. Importing 'pybluez' directly will fail.","wrong":"import pybluez","symbol":"BluetoothSocket","correct":"from bluetooth import BluetoothSocket"}],"quickstart":{"code":"import bluetooth\n\ntarget_name = \"My Device\"\ntarget_address = None\n\nnearby_devices = bluetooth.discover_devices(duration=8, lookup_names=True, flush_cache=True)\n\nfor addr, name in nearby_devices:\n    if target_name == name:\n        target_address = addr\n        break\n\nif target_address is not None:\n    print(\"Found target device with address:\", target_address)\nelse:\n    print(\"Could not find target device nearby.\")","lang":"python","description":"Discover nearby Bluetooth devices and find a device by name."},"warnings":[{"fix":"Use 'import bluetooth' or 'from bluetooth import ...'.","message":"The import uses 'bluetooth', not 'pybluez'. This is a common source of confusion.","severity":"gotcha","affected_versions":"all"},{"fix":"For modern Bluetooth development, use Bleak (cross-platform) or PyBluez2 (fork with fixes).","message":"PyBluez is no longer actively maintained; the last release (0.23) was in 2019. Consider using PyBluez2 or Bleak for new projects.","severity":"deprecated","affected_versions":"0.23 and earlier"},{"fix":"Use Bleak instead for macOS support.","message":"On macOS, PyBluez has limited functionality; many features like device discovery may not work.","severity":"gotcha","affected_versions":"all on macOS"},{"fix":"Run 'sudo usermod -a -G bluetooth $USER' and log out/in.","message":"On Linux, the 'bluetooth' user group must be added to avoid permission errors when scanning.","severity":"gotcha","affected_versions":"all on Linux"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use 'import bluetooth' or 'from bluetooth import BluetoothSocket'.","cause":"Trying to import 'pybluez' instead of 'bluetooth'.","error":"ModuleNotFoundError: No module named 'pybluez'"},{"fix":"Kill other Bluetooth processes (e.g., 'sudo systemctl stop bluetooth') or run as root.","cause":"Bluetooth adapter is in use by another process or permissions issue on Linux.","error":"bluetooth.btcommon.BluetoothError: (16, 'Device or resource busy')"},{"fix":"Add user to 'bluetooth' group: 'sudo usermod -a -G bluetooth $USER' and log out/in.","cause":"User does not have permission to access Bluetooth on Linux.","error":"bluetooth.btcommon.BluetoothError: (13, 'Permission denied')"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}