phue

modern Python library to control the Philips Hue lighting system

This is a fork of the original phue library by Nathanaël Lécaudé, modernized with type annotations, improved error handling, and a fully-featured CLI. The library remains MIT licensed.

[!IMPORTANT]

I appreciate the original authors work and if there's any interest in merging these (substantial) changes back into the original library, I'm happy to do so.

Installation

Using uv

uv add phue

uv pip install phue

Using pip

pip install phue

Repository Structure

.
├── LICENSE
├── README.md
├── examples/
├── src/
│   └── phue/
│       ├── __init__.py
│       ├── __main__.py      # CLI interface
│       ├── bridge.py        # Bridge connection handling
│       ├── exceptions.py    # Custom exceptions
│       ├── group.py         # Group controls
│       ├── light.py         # Light controls
│       ├── scene.py         # Scene handling
│       └── sensor.py        # Sensor controls
└── tests/              # Tests

Requirements

• Python 3.10 or higher (not compatible with Python 2.x)
• httpx (for network requests)

Features

• Fully typed with Python type annotations
• Robust error handling with custom exceptions
• Comprehensive test suite
• Colorful, user-friendly command-line interface
• Support for Lights, Groups, Scenes, and Sensors
• Auto-discovery of Hue bridges on the network
• Simple and intuitive API for controlling Hue devices

Command Line Usage

The library includes a command-line interface for controlling your Hue lights:

# List all lights
phue ls

# Get details about a specific light
phue get light "Living Room"

# Turn on a light and set brightness
phue set light "Kitchen" --on --bri 200

# List all groups
phue ls groups

# Turn off lights in a group
phue set group "Downstairs" --off

Basic Usage

Using the set_light and get_light methods you can control pretty much all the parameters:

from phue import Bridge

# Connect to the bridge
b = Bridge('192.168.1.100')

# If the app is not registered and the button is not pressed, press the button and call connect()
# This only needs to be run a single time
b.connect()

# Get the bridge state (This returns the full dictionary that you can explore)
b.get_api()

# Prints if light 1 is on or not
b.get_light(1, 'on')

# Set brightness of lamp 1 to max
b.set_light(1, 'bri', 254)

# Turn lamp 2 on
b.set_light(2, 'on', True)

# You can also control multiple lamps by sending a list as lamp_id
b.set_light([1, 2], 'on', True)

# You can also use light names instead of the id
b.get_light('Kitchen')
b.set_light('Kitchen', 'bri', 254)

# Also works with lists
b.set_light(['Bathroom', 'Garage'], 'on', False)

Light Objects

If you want to work in a more object-oriented way, you can get Light objects:

# Get a flat list of light objects
lights = b.lights

# Print light names
for light in lights:
    print(light.name)

# Set brightness of each light to 127
for light in lights:
    light.brightness = 127

# Get a dictionary with the light name as the key
light_names = b.get_light_objects('name')

# Set lights using name as key
for light_name in ['Kitchen', 'Bedroom', 'Garage']:
    light = light_names.get(light_name)
    if light:
        light.on = True
        light.hue = 15000
        light.saturation = 120

Error Handling

The library provides custom exceptions for better error handling:

from phue import Bridge, PhueRegistrationException, PhueRequestTimeout

try:
    b = Bridge('192.168.1.100')
    b.connect()
except PhueRegistrationException:
    print("Press the button on the bridge and try again")
except PhueRequestTimeout:
    print("Could not connect to the bridge - check your network")

Acknowledgments

This project is a fork of the original phue library created by Nathanaël Lécaudé.

The modernized version was created by zzstoatzz to add type annotations and a more opinionated CLI.

License

MIT - http://opensource.org/licenses/MIT

"Hue Personal Wireless Lighting" is a trademark owned by Koninklijke Philips Electronics N.V., see www.meethue.com for more information. I am in no way affiliated with the Philips organization.

Bridge errors

Hue may return HTTP 200 with an error object, including after partially applying a multi-property command. Bridge.request raises PhueException for these responses; check its id for the Hue error code. A link-button registration error raises PhueRegistrationException. Read back the affected lights before retrying: an exception does not mean that every part of the command was rolled back.

Transport exceptions omit the bridge application key from their messages.

Migrating to 0.1

Successful calls keep their existing return shapes. API failures raise PhueAPIError, a subclass of PhueException; this makes the error behavior first introduced in 0.0.5 an explicit part of the minor-version contract. The earlier 0.0.4 behavior returned error objects as ordinary data. Catch PhueException to handle both transport and API failures, or PhueAPIError to inspect the complete response, including partial successes:

from phue import Bridge, PhueAPIError

bridge = Bridge(ip="192.168.1.10", username="your-application-key", save_config=False)
try:
    bridge.set_light(1, {"on": True, "ct": 300})
except PhueAPIError as error:
    # The response may contain successful properties alongside errors.
    response = error.response
    current_state = bridge.get_light(1)

Lists of light or group targets are processed in order and stop on the first failure. Earlier targets may already have changed; later targets are not attempted. Unknown light or group names raise KeyError instead of being silently skipped. Passing a transition no longer adds fields to the caller's attribute dictionary.

For a long-running service, supply a caller-owned HTTP client to reuse bridge connections. The bridge borrows it; its owner manages timeout and cleanup:

import httpx
from phue import Bridge

with httpx.Client(timeout=10) as client:
    bridge = Bridge(
        ip="192.168.1.10",
        username="your-application-key",
        save_config=False,
        http_client=client,
    )
    lights = bridge.get_light()
    groups = bridge.get_group()