---
id: aioharmony
version: "1.0.8"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# aioharmony — asyncio Python library for connecting to and controlling the Logitech Harmony

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

## What it is and what it does

aioharmony is an asyncio-native Python library for remote control of Logitech Harmony hubs. It evolved from earlier synchronous harmony libraries to provide async/await support, custom event callbacks, and automatic reconnection. The library communicates with Harmony devices over WebSockets (modern firmware) or XMPP (legacy), allowing you to query device and activity configuration, start or stop activities, send device commands, and monitor hub state changes through callbacks.

The package is built on aiohttp for HTTP/WebSocket communication and includes a command-line interface for discovery and control. It handles the Harmony protocol details internally, exposing a straightforward API: connect to a hub by IP, look up activity or device IDs by name, then call methods like start_activity() or send_commands() with those IDs. Event callbacks let you react to activity changes, connection state, and configuration updates without polling.

Use it for:

- Automate home theater activities (e.g., start 'Watch TV' activity when motion is detected)
- Send device commands programmatically (volume, channel changes) from a home automation system
- Monitor current activity and trigger downstream actions when the hub switches activities
- Build a custom control interface or dashboard that queries hub configuration and sends commands
- Integrate Harmony hub control into a larger asyncio-based home automation application

## Worth the install?

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

aioharmony is an asyncio library for programmatically controlling Logitech Harmony Link and Ultimate Hub devices over the network, supporting activity management, device commands, and event callbacks.

Yes. aioharmony is actively maintained, has low install friction, carries a permissive license, and fills a clear niche for Python developers needing programmatic Harmony hub control. The asyncio design integrates well with modern Python automation frameworks. No known security vulnerabilities. Install it if you own a Harmony device and need to automate or integrate it into a Python application.

## Install

pip install aioharmony
uv add aioharmony
poetry add aioharmony

## Installing aioharmony

Before you install: Low install friction; pure Python wheel with three runtime dependencies (aiohttp, async-timeout, slixmpp). Actively maintained with recent commits and support for modern Python versions (3.10–3.14).

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart:

pip install aioharmony

import asyncio
from aioharmony.harmonyapi import HarmonyAPI

async def main():
    client = HarmonyAPI(ip_address="192.168.1.203", protocol="WEBSOCKETS")
    await client.connect()
    try:
        print(f"Connected to {client.name}")
    finally:
        await client.close()

asyncio.run(main())

Requires a Logitech Harmony device on the network accessible via IP address; WEBSOCKETS protocol requires modern firmware, XMPP is for legacy hubs.

Verify before relying:

- Whether XMPP support requires slixmpp to be explicitly configured or if it is automatically available
- Specific firmware versions supported by WEBSOCKETS vs XMPP protocols
- Whether automatic reconnect works across network interruptions or only transient disconnects

## Package facts

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

## Tags

logitech harmony control library, asyncio harmony hub automation, harmony device remote control, home automation harmony integration, harmony activity management, harmony hub python api, logitech harmony websockets, home-automation, asyncio, iot-control

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