---
id: btsocket
version: "0.3.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# btsocket — Python library for BlueZ Bluetooth Management API

License: permissive · Maintenance: aging · Downloads: 625.5K/mo

## What it is and what it does

btsocket is a low-level Python wrapper around the BlueZ Bluetooth Management API on Linux. It provides access to the kernel's mgmt socket interface for controlling Bluetooth adapters—powering them on/off, discovering devices, and managing connections—without the ability to read or write data on connected devices themselves. The library requires root or CAP_NET_ADMIN capability for most operations.

The package splits functionality into three layers: a socket layer (working around a Python limitation to access the user channel), a protocol layer for encoding and decoding binary mgmt commands and responses, and a programming paradigm layer offering both synchronous (blocking) and callback-driven (event-based) APIs. It is explicitly positioned as an early-stage proof of concept and not recommended as a first Bluetooth library for newcomers.

Use it for:

- Automate Bluetooth adapter power management and discovery on embedded Linux systems
- Build home automation scripts that scan for and manage Bluetooth device presence
- Develop educational projects exploring the BlueZ stack and low-level Bluetooth protocol
- Monitor and control Bluetooth adapters programmatically in system administration tools
- Create event-driven applications that react to Bluetooth device discovery or connection changes

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Python library for controlling BlueZ Bluetooth adapters on Linux via the Management API, supporting both synchronous and event-driven command patterns.

Yes, if you need direct access to BlueZ's management API on Linux and are comfortable with root-level operations and early-stage code. No, if you are new to Bluetooth, need data I/O on connected devices, or require a mature, actively maintained library. The aging maintenance status suggests caution for production use.

## Install

pip install btsocket
uv add btsocket
poetry add btsocket

## Installing btsocket

Before you install: Low install friction with no runtime dependencies. Maintenance is aging—last release was over a year ago and the repository shows limited activity (18 stars), though it remains unarchived.

License in practice: MIT license is permissive; you may use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install btsocket

from btsocket import btmgmt_sync
response = btmgmt_sync.send('SetPowered', 0, 1)

Requires root or CAP_NET_ADMIN capability; Linux-only; works around Python socket limitation documented at https://bugs.python.org/issue36132

Verify before relying:

- Whether the library works with modern Python versions (requires_python is unspecified)
- Current state of the Python socket bug at https://bugs.python.org/issue36132 and whether it affects current releases
- Compatibility with recent BlueZ versions and Linux kernel releases

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 625.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

bluez bluetooth management api python, linux bluetooth control library, bluetooth device discovery python, mgmt socket bluetooth, bluetooth adapter control, bluez python wrapper, bluetooth management commands, bluetooth, linux-only, requires-root

[View on SkillFed](https://skillfed.io/packages/btsocket) · [View on PyPI](https://pypi.org/project/btsocket/)