phue: a single-file Python client for the Philips Hue bridge

What the library covers

phue is a full featured Python library to control the Philips Hue lighting system, and the feature list is short and specific. It is compliant with the Philips Hue API 1.0, and it supports Lights, Groups, Schedules, Scenes and Sensors. It is compatible with Python 2.6.x and upwards and with Python 3, it has no dependencies, and it has a simple structure with a single phue.py file. The last point is the one that shapes everything else, because it means the library works on a Raspberry Pi running an old Python without a dependency resolver in the way, and it means you can copy one file into a project. The primary language is Python, the licence is MIT according to the README and the setup script, the last push was on 2026-09-22, and the releases are 1.1 on 2020-07-17 with older r9 and r8 tags. The repository also has a `TODO.md` and a `CHANGELOG.md` at the root.

Installing it, three ways

The installation section is old-fashioned in a way that still works. Via distutils it is `sudo easy_install phue`:

sudo easy_install phue

or with pip:

pip install phue

Or manually, since phue consists of a single file, phue.py, that you can put in your python search path or in site-packages, or in dist-packages depending on the platform, and you can also simply run it by putting it in the same directory as your main script file, or start a python interpreter in the same directory. The `setup.py` at the root uses distutils with `py_modules=['phue']` and pulls the version from the module's own `__version__` attribute, which is a small detail worth knowing because the version lives in the library file rather than in the packaging metadata. The repository also carries a `tox.ini` and a `test-requirements.txt` for running the tests in `tests/`, and a `.travis.yml` from the era when that was the CI of record.

The bridge handshake, and the procedural style

The basic usage pattern is procedural, and it begins with the bridge rather than a light. You create a `Bridge` with the IP address of your bridge, and if the app is not registered and the button is not pressed, you press the button and call `connect()`, which only needs to be run a single time. From there the bridge methods cover the API. `get_api()` returns the full dictionary that you can explore, `get_light(1, 'on')` reads a property, and `set_light(1, 'bri', 254)` writes one. You can control multiple lamps by sending a list as the lamp id, and you can use light names instead of ids, so `b.set_light('Kitchen', 'bri', 254)` works and so does a list of names. The `set_light` method can also take a dictionary as the second argument for a more complex command, which is how you combine a transition time with a brightness in one call. The README's philosophy is stated as working in a procedural way or an object oriented way, and both are supported at once.

The object-oriented interface, and three ways to key the lights

If you prefer objects, there are several ways to get `Light` objects, and the difference is only in how the collection is keyed. `b.lights` gives a flat list, and the example iterates over it setting brightness to 127. `b.get_light_objects('id')` gives a dictionary keyed by the light id, and `b.get_light_objects('name')` gives one keyed by the light name, and `b.get_light_objects('list')` gives the flat list again. The named form is the one worth using, because the example sets `on`, `hue` and `saturation` on lights addressed by name, and the attribute style is what makes a script read like the thing it controls. The Light objects expose properties as attributes, so `light_names['Kitchen'].brightness = 254` and `light.on = True` are the same operations as the procedural calls, just spelled differently.

Transition times, and the known brightness bug

Transition times are one of the places where the Hue API is awkward. In the API they are specified in deciseconds, tenths of a second, and this is not tracked as a device setting but rather needs to be applied on each individual transition command you want to control the time of, so you pass a `transitiontime` keyword when calling `set_light` on the bridge. As a convenience, the Light class implements a wrapper that remembers a specified transition time for that light and applies it automatically to every transition, so you set `light.transitiontime = 2` once and the next change is fast. The documentation is candid about a known bug, where turning a light off with the transitiontime specified can cause the brightness level to behave erratically when the light is turned back on, and the package attempts to work around it by automatically resetting the brightness when necessary, but that may not work in all cases. Transition times from 0 to 300 deciseconds, meaning 0 to 30 seconds, have been tested to work.

Groups, schedules and the timezone trap

Groups work through the bridge methods, with `get_group`, `set_group`, `create_group` and `delete_group`, and the README notes that if groups are not working you should try re-setting the bridge by unplugging it and plugging it back in, which is a real Hue troubleshooting step rather than a joke. Schedules are handled with `get_schedule`, `create_schedule`, `create_group_schedule` and `delete_schedule`. The detail worth knowing is the timezone behaviour, because the README states that updates to the Hue API now use local time instead of UTC, and that if you have issues with schedules not triggering correctly you should double check that the time zone is set correctly on your Hue Bridge and that your time in your code is not in UTC by default. That is a whole class of silent failure in one sentence, because a schedule that never fires is indistinguishable from a broken one.

The examples, and the two unusual runtimes

The `examples/` directory shows the range of what the library is for, and the file names describe the use cases. There is `flicker.py`, `hue-rainbow.py`, `random_colors.py` and `rgb_colors.py` for the small scripted effects, and four Tkinter interfaces, `tk_gui_simple.py`, `tk_gui_hsb.py`, `tk_gui_complex.py` and a shared example, which is a desktop control panel built on the library. There are also two documented ways to run phue somewhere unusual. You can use it within Max/MSP through Nick Rothwell's Jython objects, with a version updated to support Jython 2.7 which the README says is required for phue to work. And you can use it on an iOS device via the Pythonista app, which the README presents as a way to build quick prototypes on iOS without compiling anything, since you can code directly from the device. The acknowledgements credit the person who hacked the protocol in the first place.

Editorial conclusion

Adopt phue if you want to control Hue lights from Python with nothing to install alongside it, since the library is a single file with no dependencies. Skip it if you need Hue Entertainment, Hue Go or newer bridge features, since the documented scope is the 1.0 API and the newest tagged release is 1.1 from 2020-07-17 even though the last push was on 2026-09-22. Before you automate anything, run `b.connect()` once with the bridge button pressed, and note that schedule times are interpreted in local time rather than UTC, so a misconfigured bridge time zone will silently produce schedules that never fire.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. studioimaginaire/phue on GitHub