PyBluez

0.23 verified Fri May 01 auth: no python maintenance

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.

pip install pybluez

Common errors

error ModuleNotFoundError: No module named 'pybluez' ↓

cause Trying to import 'pybluez' instead of 'bluetooth'.

fix

Use 'import bluetooth' or 'from bluetooth import BluetoothSocket'.

error bluetooth.btcommon.BluetoothError: (16, 'Device or resource busy') ↓

cause Bluetooth adapter is in use by another process or permissions issue on Linux.

fix

Kill other Bluetooth processes (e.g., 'sudo systemctl stop bluetooth') or run as root.

error bluetooth.btcommon.BluetoothError: (13, 'Permission denied') ↓

cause User does not have permission to access Bluetooth on Linux.

fix

Add user to 'bluetooth' group: 'sudo usermod -a -G bluetooth $USER' and log out/in.

Warnings

gotcha The import uses 'bluetooth', not 'pybluez'. This is a common source of confusion. ↓

fix Use 'import bluetooth' or 'from bluetooth import ...'.

deprecated PyBluez is no longer actively maintained; the last release (0.23) was in 2019. Consider using PyBluez2 or Bleak for new projects. ↓

fix For modern Bluetooth development, use Bleak (cross-platform) or PyBluez2 (fork with fixes).

gotcha On macOS, PyBluez has limited functionality; many features like device discovery may not work. ↓

fix Use Bleak instead for macOS support.

gotcha On Linux, the 'bluetooth' user group must be added to avoid permission errors when scanning. ↓

fix Run 'sudo usermod -a -G bluetooth $USER' and log out/in.

Imports

BluetoothSocket
wrong
```
import pybluez
```
correct
```
from bluetooth import BluetoothSocket
```
The main module is named 'bluetooth', not 'pybluez'. Importing 'pybluez' directly will fail.

Quickstart

Discover nearby Bluetooth devices and find a device by name.

import bluetooth

target_name = "My Device"
target_address = None

nearby_devices = bluetooth.discover_devices(duration=8, lookup_names=True, flush_cache=True)

for addr, name in nearby_devices:
    if target_name == name:
        target_address = addr
        break

if target_address is not None:
    print("Found target device with address:", target_address)
else:
    print("Could not find target device nearby.")