pyheos

What it is and what it does

pyheos is an async Python library that connects to Denon and Marantz audio products equipped with HEOS Built-in, allowing you to control them programmatically over the local network. It implements the HEOS CLI Protocol (version 1.21) and provides a single connection point to manage all compatible devices on your network, with support for player discovery, playback commands, event subscriptions, and automatic reconnection. The library is designed around async/await patterns and includes options for heart-beat monitoring, event filtering, account sign-in, and failover to alternate hosts.

The main entry point is the `Heos` class, which you instantiate via `create_and_connect()` with a host IP address and optional configuration. Once connected, you can retrieve available players, subscribe to state changes through a dispatcher, and issue control commands. It requires Python 3.11 or newer and has no external runtime dependencies, making it lightweight to integrate into home automation frameworks or standalone scripts.

Use it for:

• Automate multi-room audio playback across HEOS devices in a home automation system.
• Build a custom control interface or dashboard for Denon/Marantz HEOS speakers and receivers.
• Monitor and react to player state changes (play, pause, track changes) via event subscriptions.
• Implement failover logic to maintain control when the primary HEOS device becomes unavailable.
• Integrate HEOS device control into a larger smart home orchestration platform.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

An asynchronous Python library for controlling Denon and Marantz HEOS devices over the local network via the HEOS CLI Protocol, supporting device discovery, playback control, and event notifications.

Yes. The package is actively maintained, has no external dependencies, supports current Python versions (3.11+), carries a permissive license, and has no known vulnerabilities. It fills a clear niche for HEOS device automation. Install it if you own compatible Denon or Marantz equipment and need programmatic control; skip it if you have no HEOS devices or prefer a different audio ecosystem.

Install

pyheos on PyPI

pip install pyheos

uv add pyheos

poetry add pyheos

Installing pyheos

Before you install

Low friction: pure Python wheel with no runtime dependencies. Actively maintained as of June 2026 with recent releases; requires Python 3.11 or newer.

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions.

Quickstart

pip install pyheos

import pyheos

heos = await pyheos.Heos.create_and_connect('172.16.0.1', auto_reconnect=True)
players = await heos.get_players()
await heos.disconnect()

Requires Python 3.11 or newer; target HEOS device must be on the same local network and running HEOS firmware 3.40 or newer.

Verify before relying

• Whether the library supports HEOS firmware versions older than 3.40 despite the stated requirement.
• Performance characteristics when managing large numbers of HEOS devices or players on a single connection.
• Availability and completeness of API documentation beyond the excerpt provided.

Package facts

Evidence: pyheos-1.0.6-py3-none-any.whl

Keywords: heos, dennon, maranz

Tags

More Libraries packages