HueBLE
Python module for controlling Bluetooth Philips Hue lights.
- 👌 Free software: MIT license
- 🍝 Sauce: https://github.com/flip-dots/HueBLE
- 🖨️ Documentation: https://hueble.readthedocs.io/en/latest/
- 📦 PIP: https://pypi.org/project/HueBLE/
This Python module enables you to control Philips Hue Bluetooth lights directly from your computer, without the need for a Hue bridge or ZigBee dongle. It leverages the Bleak library to interact with Bluetooth Philips Hue lights including the smart plugs.
Features
- 💡 On/Off control
- 🌗 Brightness control
- 🌡️ Colour temp control
- 🌈 XY colour control
- ✨ Built-in effects with custom colour and speed
- ⏱️ Custom transitions, including instant changes
- ❔ Light state (power/brightness/temp/colour)
- ⚙️ Light configuration (name)
- 📊 Light metadata (manufacturer/model/zigbee address)
- 🤜 Supports push & polling models
- 🔌 Hue smart plug support
- 🔂 Simple structure
- 📜 Mediocre documentation
- ✔️ More emojis than strictly necessary
Requirements
- 🐍 Python 3.11+
- 📶 Bleak 0.19.0+
- 📶 bleak-retry-connector
Supported Operating Systems
- 🐧 Linux (BlueZ)
- Ubuntu Desktop (24.04)
- Arch
- Buildroot (HomeAssistant OS)
- 🏢 Windows
- Windows 10
- 💾 Mac OSX
- Sequoia (15.7)
- 🛜 ESPHome (Bluetooth Proxy)
- ESP32-C3-Super-Mini
- ESP32-C5-N4R2
Documentation
https://hueble.readthedocs.io/en/latest/
Installation
PIP
pip install HueBLE
Manual
HueBLE consists of a single file (HueBLE.py) which you can simply put in the same directory as your program. If you are using manual installation make sure the dependencies are installed as well.
pip install bleak bleak-retry-connector dbus-fast
Examples
Quick start example
Example code from example.py
import asyncio
from bleak import BleakScanner
import HueBLE
async def main():
# Address of light to connect to
address = "F6:9B:48:A4:D2:D8"
# Obtain the BLEDevice from bleak
device = await BleakScanner.find_device_by_address(address)
# Initialize the light object
light = HueBLE.HueBleLight(device)
# Optionally we could call connect but it will be called automatically
# on the first request to the light. You might want to call this if
# you want to subscribe to state changes without changing the lights state.
# await light.connect()
# Will automatically connect to the light and turn it off
await light.set_power(False)
# Wait
await asyncio.sleep(5)
# Turn the light back on again
await light.set_power(True)
if __name__ == "__main__":
asyncio.run(main())
Transitions
Power, brightness, colour temperature and colour changes can use a custom transition time.
await light.set_power(True, transition_ms=0)
await light.set_brightness(254, transition_ms=100)
await light.set_colour_temp(250, transition_ms=400)
await light.set_colour_xy(0.3, 0.4, transition_ms=200)
transition_ms=0 makes the change instant. Transition times use 100 ms steps.
Effects
HueBLE supports Hue effects such as Candle, Fireplace, Sunrise and Sunset. Effects can use a custom colour, brightness and speed.
await light.set_colour_effect(
0.30,
0.14,
254,
HueBLE.EffectType.CANDLE,
128,
)
Effect speed ranges from 0 (slowest) to 255 (fastest).
Demo program
A more fully featured demo program can be found in examples/demo.py which demonstrates all of the implemented features.
Disclaimer
HueBLE is a software library designed to work with Philips Hue. Philips Hue is a registered trademark of Philips. This project is not affiliated with, endorsed by, or sponsored by Philips (Though I wouldn't mind being sponsored 😉). All other trademarks cited herein are the property of their respective owners.
Metadata
Release files for HueBLE 2.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hueble-2.3.0.tar.gz | 25.0 kB | With provenance | Details for hueble-2.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hueble-2.3.0-py3-none-any.whl | Python 3 | none | any | Details for hueble-2.3.0-py3-none-any.whl |
Total release size: 42.7 kB
Release files / hueble-2.3.0.tar.gz
| Download URL | hueble-2.3.0.tar.gz |
|---|---|
| Size | 25.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
640dc8106c6dd7b7eb1181266fc00a8e408343318519c5f4795da3d7605a6e17
|
|
BLAKE2b-256 checksum How to use checksums |
b68799b7fa3892507dffc2b618777fd01c2091608d1a141b86fcd6bbcb226bd1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / hueble-2.3.0-py3-none-any.whl
| Download URL | hueble-2.3.0-py3-none-any.whl |
|---|---|
| Size | 17.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d8fff7c3e42cfc38cbf2ff78d06b4f15e323bc09cf353d76a4ca60d9ddd04a4d
|
|
BLAKE2b-256 checksum How to use checksums |
79e6226e4b24c87c05ae23c3b5039d22063d4d950a36f95ed7e9f8bb56b05d9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for HueBLE 2.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hueble-2.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.