pyatv

0.17.0 verified Fri May 01 auth: no python

A Python client library for controlling Apple TV and AirPlay devices. It supports scanning, pairing, and remote control via MRP, Companion, and AirPlay protocols. Current version 0.17.0 requires Python 3.9+, and releases occur roughly every 3-6 months.

pip install pyatv

Common errors

error ImportError: cannot import name 'scan' from 'pyatv' ↓

cause Outdated version of pyatv (pre-0.7.0) where scan was not a public top-level function.

fix

Upgrade pyatv: pip install --upgrade pyatv

error RuntimeError: TimeoutError raised as AuthenticationError ↓

cause Known issue in pyatv <0.14.2 where TimeoutError during connection was incorrectly re-raised as AuthenticationError, causing frequent reconfiguration in Home Assistant.

fix

Upgrade to pyatv 0.14.2 or later.

error TypeError: object dict can't be used in 'await' expression ↓

cause Trying to use pyatv functions without async/await context or passing coroutines to asyncio.wait incorrectly.

fix

Ensure all pyatv calls are awaited inside an async function, and on Python 3.11+ use asyncio.create_task for coroutines passed to asyncio.wait.

error ModuleNotFoundError: No module named 'pydantic' ↓

cause pydantic is a required dependency missing from the environment.

fix

Install both pyatv and pydantic: pip install pyatv pydantic>=2

Warnings

breaking In 0.17.0, support for pydantic v1 was dropped. You must have pydantic 2.x installed. ↓

fix Run: pip install 'pydantic>=2'

breaking Python 3.9+ required. Python 3.8 support dropped in 0.16.0. ↓

fix Upgrade Python to 3.9 or later.

deprecated The `imghdr` module (via mediafile) was removed in 0.16.0. The library now uses tinytag for metadata. ↓

fix If you relied on imghdr, reimplement using other means.

gotcha On tvOS 18.4+, connection may fail. Fixed in 0.16.1 but still may appear. ↓

fix Ensure you are using at least pyatv 0.16.1.

gotcha Async functions require an explicit loop argument; passing coroutines directly to asyncio.wait (allowed in Python <3.11) raises an error in Python 3.11+. Fixed in 0.14.4. ↓

fix Upgrade pyatv to 0.14.4+ or wrap coroutines in asyncio.create_task.

gotcha The pyatv package name on PyPI is `pyatv`, but some users mistakenly import `pyatv` as `pyatv` (correct) or try `pyatv.client`. Only the top-level module is available. ↓

fix Use `import pyatv` and access submodules like `pyatv.const`.

Imports

pyatv
```
import pyatv
```
scan
wrong
```
from pyatv.core import scan
```
correct
```
from pyatv import scan
```
scan is a top-level function, not in pyatv.core.
connect
wrong
```
from pyatv import interface
```
correct
```
from pyatv import connect
```
The correct way is to use pyatv.connect.
const
wrong
```
import pyatv.const
```
correct
```
from pyatv import const
```
top-level module, import as shown.

Quickstart

Scan for Apple TV devices, connect to the first one found, and send a play/pause command.

import asyncio
from pyatv import scan, connect

async def example():
    devices = await scan(loop=asyncio.get_running_loop(), timeout=5)
    if not devices:
        print("No Apple TV found")
        return
    atv = devices[0]
    print(f"Found: {atv.name} at {atv.address}")
    try:
        conn = await connect(atv, loop=asyncio.get_running_loop())
        print("Connected successfully")
        # Example: play/pause
        await conn.remote_control.play_pause()
        conn.close()
    except Exception as e:
        print(f"Connection failed: {e}")

asyncio.run(example())