Registry / communication / simplepyble

simplepyble

JSON →
library0.14.0pypypi✓ verified 85d ago

SimplePyBLE provides Python bindings for SimpleBLE, a fully cross-platform Bluetooth Low Energy (BLE) library written in C++. It is designed for simplicity and ease of use, offering a consistent API across Windows, macOS, and Linux, with some support for iOS and Android. The library is currently at version 0.12.1 and maintains an active release cadence, with frequent updates addressing features, stability, and bug fixes.

pip install simplepyble
INSTALL
IMPORT
SIG · SIMPLEPYBLE
S
simplepyble
communicationpythonv0.14.0
Install
2.3s avg
Import
4ms
Disk
24MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.14.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
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.3s · import 0.003s · 26MB
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Adapter
from simplepyble import Adapter
Standard import for synchronous BLE operations.
Adapter
from simplepyble.aio import Adapter
Import for asyncio-compatible, asynchronous BLE operations, introduced in v0.12.1. This is the recommended way for async applications.

This asynchronous quickstart demonstrates how to initialize an adapter, scan for Bluetooth Low Energy (BLE) peripherals, and connect to a discovered device. It uses the `simplepyble.aio` module, which offers an `asyncio`-compatible API with automatic callback cleanup and context manager support for robust asynchronous operations.

import asyncio from simplepyble.aio import Adapter async def main(): adapters = Adapter.get_adapters() if not adapters: print("No adapters found. Ensure Bluetooth is on and permissions are granted.") return # Use the first adapter found adapter = adapters[0] print(f"Selected adapter: {adapter.identifier()} [{adapter.address()}]") # Use the adapter within an async context manager async with adapter: print("Scanning for 5 seconds...") await adapter.scan_for(5000) # Scan for 5000 milliseconds peripherals = adapter.scan_get_results() if not peripherals: print("No peripherals found.") return print("Found peripherals:") for i, peripheral in enumerate(peripherals): print(f" [{i}] {peripheral.identifier()} [{peripheral.address()}] - Connectable: {peripheral.is_connectable()}") # Example: Connect to the first connectable peripheral found connectable_peripherals = [p for p in peripherals if p.is_connectable()] if connectable_peripherals: selected_peripheral = connectable_peripherals[0] print(f"Attempting to connect to: {selected_peripheral.identifier()}") await selected_peripheral.connect() print(f"Successfully connected to {selected_peripheral.identifier()}") # Discover services and characteristics (example) services = selected_peripheral.services() for service in services: print(f" Service: {service.uuid()}") for characteristic in service.characteristics(): print(f" Characteristic: {characteristic.uuid()} (Can Read: {characteristic.can_read()})") await selected_peripheral.disconnect() print(f"Disconnected from {selected_peripheral.identifier()}") else: print("No connectable peripherals found to demonstrate connection.") if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
breakingAs of v0.9.0 (January 2025), SimpleBLE (and thus SimplePyBLE) has changed its license to Business Source License 1.1 (BUSL-1.1). Commercial use requires a commercial license, though free licenses are offered for small projects. Ensure your project's licensing is compatible.
fix
Review the new license terms (BUSL-1.1) for compliance with your project's use case. Contact SimpleBLE maintainers for commercial licensing inquiries if needed.
affects: >=0.9.0
gotchaVersions prior to v0.10.3 (June 2025) and v0.10.2 (June 2025) experienced several deadlocks and GIL issues within the Python bindings, particularly on Windows when interacting with WinRT threading models. This could lead to application freezes or crashes.
fix
Upgrade to simplepyble v0.10.3 or newer to benefit from stability fixes related to threading and GIL management.
affects: <0.10.3
gotchaThe `simplepyble.aio` module, providing an `asyncio`-compatible API, was introduced in v0.12.1 (February 2026). If you are using an older version or trying to implement asynchronous operations with the synchronous API, you might encounter blocking behavior or need to manually manage threads.
fix
For asynchronous applications, use `from simplepyble.aio import Adapter` and follow the `asyncio` patterns. For older versions, consider upgrading or using separate threads for blocking BLE operations if a responsive UI is required.
affects: <0.12.1
Errors
Common errors & fixes
FileNotFoundError: [WinError 2] The system cannot find the file specified
This error typically occurs during `pip install simplepyble` on Windows, especially with newer Python versions (e.g., 3.13), indicating that necessary C++ build tools or SDK components are missing for compiling the underlying C++ library.
fix
Ensure that the 'Desktop development with C++' workload is installed in Visual Studio, including 'MSVC v143 - VS 2022 C++ x64/x86 build tools' and 'Windows 10/11 SDK'. If problems persist, consider trying a slightly older Python version for which pre-built wheels might be available.
DLL load failed while importing _simplepyble: The specified module could not be found.
This error appears when attempting to `import simplepyble` on Windows, even after a seemingly successful installation. It means the Python bindings (`_simplepyble.pyd`) cannot find required runtime DLLs on the system's PATH, such as Visual C++ Redistributables.
fix
Install the latest Microsoft Visual C++ Redistributable for your system (x64 and/or x86) from the official Microsoft website. Ensure any other system-level dependencies are correctly installed and visible in the system's PATH.
ERROR: Failed building wheel for simplepyble
During `pip install simplepyble` on Linux, this indicates a failure to compile the C++ backend. A common reason is missing system development headers, particularly for D-Bus.
fix
Install the necessary development packages. For Debian/Ubuntu-based systems, run: `sudo apt-get update && sudo apt-get install libdbus-1-dev`. Adapt for other distributions (e.g., `dnf install dbus-devel` on Fedora, `pacman -S dbus` on Arch).
No adapters found
When `Adapter.get_adapters()` returns an empty list or your program immediately exits with this message, it usually means no Bluetooth adapter is active, available, or the application lacks the necessary permissions to access it.
fix
Verify that your Bluetooth hardware is enabled and turned on. On Linux, ensure your user has permissions to access Bluetooth devices (e.g., `sudo usermod -a -G bluetooth $USER` and reboot). Restart the Bluetooth service if necessary (e.g., `sudo systemctl restart bluetooth`).
Upgrade
Version history
0.14.0latest on PyPI · released May 2, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.8 or newer.
libdbus-1-devrequiredRequired for D-Bus integration on Linux systems. Install via system package manager (e.g., apt).
Agent activity
32 hits · last 30 days
node
28
OpenAI (training)
1
Resources
simplepyble — pip install simplepyble · libregistry