---
id: pyheos
version: "1.0.6"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# pyheos — An async python library for controlling HEOS devices through the HEOS CLI Protocol

License: permissive · Maintenance: active · Downloads: 95.7K/mo

## 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 above — 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

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

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 95.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

heos device control python, denon marantz network audio, async heos cli protocol, home audio system automation, multi-room speaker control, heos player management, network audio streaming control, home-automation, async-io, network-audio

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