Installation

Pick the right SimpleBLE package or source build path for your language and platform.

SimpleBLE is a family of libraries. Start by choosing the binding that matches your application, then install the platform dependencies that binding needs.

Choose a binding

Binding	Language	Status	Best fit	Install path
SimpleBLE	C++	Production-ready	Native desktop, mobile native code, shared libraries	CMake from source
SimpleCBLE	C	Production-ready	C applications, FFI, language bridges	CMake from source
SimplePyBLE	Python	Production-ready	Scripts, tools, data pipelines, tests	PyPI or local source
SimpleJavaBLE	Java	Early Preview	JVM desktop apps and prototypes	Gradle from source
SimpleRsBLE	Rust	Early Preview	Rust applications and async workflows	crates.io or local path
SimpleDroidBLE	Kotlin / Android	Alpha	Android-only applications	Gradle composite build
SimpleBluez	C++	Lower-level utility	Direct BlueZ integration on Linux	CMake from source
SimpleDBus	C++	Lower-level utility	DBus object model work	CMake from source
SimpleAIBLE	Python / AI agents	Utility package	Local BLE tools for agents and HTTP/MCP workflows	`uv` or PyPI

Platform prerequisites

Platform	Required setup
Linux	BlueZ, DBus development headers, and permission to access the system Bluetooth stack. On Ubuntu, install `libdbus-1-dev`.
Windows	Windows 10 or newer and Windows SDK `10.0.19041.0` or newer. Build and run 64-bit applications on 64-bit Windows.
macOS	macOS 13.0 or newer and Xcode Command Line Tools. Packaged apps need Bluetooth usage strings in `Info.plist`.
iOS	iOS 15.8 or newer and the normal CoreBluetooth permission flow.
Android	API 31 or newer, Android Studio, Android NDK, manifest permissions, and runtime Bluetooth permission requests.

See Bluetooth Permissions for the OS-specific permission details that are easy to miss on first adoption.

Install commands

Build and install the C++ library from source:

git clone https://github.com/simpleble/simpleble.git
cd simpleble

cmake -S simpleble -B build_simpleble
cmake --build build_simpleble -j
cmake --install build_simpleble --prefix "$PWD/install_simpleble"

Consume the installed package from your own CMake project:

find_package(simpleble REQUIRED CONFIG)
target_link_libraries(your_app PRIVATE simpleble::simpleble)

For a local vendored build, add the library directly:

add_subdirectory(path/to/simpleble/simpleble ${CMAKE_BINARY_DIR}/simpleble)
target_link_libraries(your_app PRIVATE simpleble::simpleble)

Build and install the C wrapper from source:

git clone https://github.com/simpleble/simpleble.git
cd simpleble

cmake -S simplecble -B build_simplecble
cmake --build build_simplecble -j
cmake --install build_simplecble --prefix "$PWD/install_simplecble"

Consume the installed package from CMake:

find_package(simplecble REQUIRED CONFIG)
target_link_libraries(your_app PRIVATE simplecble::simplecble)

If you are compiling manually, include simplecble headers and link both simplecble and the platform Bluetooth dependencies.

Install the Python binding from PyPI:

pip install simplepyble

Linux users also need DBus headers:

sudo apt-get install libdbus-1-dev

Install from a local checkout when developing SimplePyBLE itself:

git clone https://github.com/simpleble/simpleble.git
cd simpleble
pip install .

SimpleJavaBLE is currently consumed from a source checkout. Build the Java package and native library with Gradle:

git clone https://github.com/simpleble/simpleble.git
cd simpleble/simplejavable/java
../../utils/gradle/gradlew build -PbuildFromCMake

Use the generated JAR from simplejavable/java/build/libs in your JVM application. The JAR must include or be able to find the simplejavable native library for your platform.

Add the Rust crate:

cargo add simplersble

Linux users need DBus headers before building:

sudo apt-get install libdbus-1-dev

If you want to use a local checkout while developing:

[dependencies]
simplersble = { path = "path/to/simpleble" }

SimpleDroidBLE is currently consumed as a Gradle composite build from a local checkout.

In settings.gradle.kts, include the library before include(":app"):

includeBuild("path/to/simpleble/simpledroidble") {
    dependencySubstitution {
        substitute(module("org.simpleble.android:simpledroidble")).using(project(":simpledroidble"))
    }
}

include(":app")

Then add the dependency:

dependencies {
    implementation("org.simpleble.android:simpledroidble")
}

The app must also declare and request Bluetooth permissions at runtime.

Install with uv:

uv tool install simpleaible

Or with pip:

pip install simpleaible

Then run the MCP server:

simpleaible

See MCP Server and HTTP Server for agent and HTTP workflows.

Verify the install

The fastest smoke test is to scan for nearby devices:

C++, C, Python, Java, Rust, and Android users can start with Quickstart.
CMake users can build the repository examples from SimpleBLE Examples or SimpleCBLE Examples.
Python users can run the examples under examples/simplepyble.
Rust users can run the examples under examples/simplersble.
Android users can run the example app under examples/simpleble-android.

Installation

Choose a binding

Platform prerequisites

Install commands

Verify the install

On this page