Install & Compatibility
Where this runs
tested against v? · pip install
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.95 runs
build_error
glibcpy 3.10–3.95 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BluetoothSocket
✓ from bluetooth import BluetoothSocket
✗ import pybluez
The main module is named 'bluetooth', not 'pybluez'. Importing 'pybluez' directly will fail.
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.")
Debug
Known issues
gotchaThe import uses 'bluetooth', not 'pybluez'. This is a common source of confusion.fixUse 'import bluetooth' or 'from bluetooth import ...'.
affects: all
deprecatedPyBluez is no longer actively maintained; the last release (0.23) was in 2019. Consider using PyBluez2 or Bleak for new projects.fixFor modern Bluetooth development, use Bleak (cross-platform) or PyBluez2 (fork with fixes).
affects: 0.23 and earlier
gotchaOn macOS, PyBluez has limited functionality; many features like device discovery may not work.fixUse Bleak instead for macOS support.
affects: all on macOS
gotchaOn Linux, the 'bluetooth' user group must be added to avoid permission errors when scanning.fixRun 'sudo usermod -a -G bluetooth $USER' and log out/in.
affects: all on Linux
Upgrade
Version history
0.23latest on PyPI · released Dec 28, 2019
Audit
Dependencies
PyBluezrequiredOn Windows, the PyBluez installer may require Visual C++ Redistributable; on Linux, bluez and libbluetooth-dev are system dependencies.