---
id: hyperion-py
version: "0.7.6"
license: MIT
license_treatment: permissive
maintenance: aging
---

# hyperion-py — Hyperion Ambient Lighting Python Package

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

## What it is and what it does

Hyperion-py is an async Python client for Hyperion-NG, a popular ambient lighting system that drives LED strips based on screen content or manual control. The library provides a thin, direct mapping to Hyperion's JSON API—no convenience wrappers or abstraction layers—so that changes to the server's data model flow through to your code without the library becoming a bottleneck. You instantiate a HyperionClient with a host and optional port, connect asynchronously, and then call methods like async_set_color(), async_set_effect(), or async_led_stream_start() to control lighting. The library handles authentication, instance switching, and background task management for you, and supports callbacks for server-side state updates.

The package has no runtime dependencies beyond Python itself, making it lightweight to install. It supports Python 3.8 through 3.13 and is licensed under MIT. The library is aging—last released 439 days ago—but the repository remains active and the code is stable for the current Hyperion-NG API surface. If your Hyperion server version matches the JSON API documentation the library was built against, this is a straightforward way to script lighting control from Python.

Use it for:

- Automate ambient lighting scenes in a home automation system by sending color or effect commands to a Hyperion-NG server.
- Stream live LED color data from a video source or custom algorithm to synchronized lighting hardware via Hyperion.
- Query and monitor Hyperion server state (brightness, active effects, component status) from a Python application.
- Build a web dashboard or mobile app backend that controls Hyperion lighting by wrapping this client.
- Integrate Hyperion lighting control into a media center or game launcher that responds to content changes.

## Worth the install?

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

A Python async client library for controlling Hyperion-NG ambient lighting systems via their JSON API, providing direct access to color, effect, and LED stream control.

Yes, if you own a Hyperion-NG setup and need Python control. The library is stable, dependency-free, and directly mirrors the official JSON API, reducing the risk of breakage when Hyperion updates. The 439-day release gap is a minor concern—verify that your Hyperion server version aligns with the API docs the library targets—but the active repository and permissive license make it a safe choice for home automation or media integration projects.

## Install

pip install hyperion-py
uv add hyperion-py
poetry add hyperion-py

## Installing hyperion-py

Before you install: Low friction installation with no runtime dependencies. Maintenance status is aging—last commit was 2025-06-01 and the package has not been released for 439 days, though the repository remains active and not archived.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute this package freely provided you retain the license notice.

Quickstart:

pip install hyperion-py

import asyncio
from hyperion import client

async def main():
    async with client.HyperionClient("hyperion-host") as hc:
        info = await hc.async_get_serverinfo()
        print(info)

asyncio.run(main())

Requires Python 3.8 or later; Hyperion-NG server must be running and accessible at the specified host and port (default 19444).

Verify before relying:

- Whether the 439-day gap since last release indicates the package is stable or abandoned relative to ongoing Hyperion-NG server development.
- Compatibility with recent Hyperion-NG server versions and whether the JSON API alignment claim remains current.

## Package facts

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

## Tags

hyperion ambient lighting control, hyperion-ng python client, led lighting automation, async hyperion api, home ambient lighting python, hyperion color effects, led stream control, home-automation, ambient-lighting, async-client

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