Install & Compatibility
Where this runs
tested against v0.17.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
scan
✓ from pyatv import scan
✗ from pyatv.core import scan
scan is a top-level function, not in pyatv.core.
connect
✓ from pyatv import connect
✗ from pyatv import interface
The correct way is to use pyatv.connect.
const
✓ from pyatv import const
✗ import pyatv.const
top-level module, import as shown.
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())
pyatv --version
Errors
Common errors & fixes
ImportError: cannot import name 'scan' from 'pyatv'
Outdated version of pyatv (pre-0.7.0) where scan was not a public top-level function.
fixUpgrade pyatv: pip install --upgrade pyatv
RuntimeError: TimeoutError raised as AuthenticationError
Known issue in pyatv <0.14.2 where TimeoutError during connection was incorrectly re-raised as AuthenticationError, causing frequent reconfiguration in Home Assistant.
fixUpgrade to pyatv 0.14.2 or later.
TypeError: object dict can't be used in 'await' expression
Trying to use pyatv functions without async/await context or passing coroutines to asyncio.wait incorrectly.
fixEnsure all pyatv calls are awaited inside an async function, and on Python 3.11+ use asyncio.create_task for coroutines passed to asyncio.wait.
ModuleNotFoundError: No module named 'pydantic'
pydantic is a required dependency missing from the environment.
fixInstall both pyatv and pydantic: pip install pyatv pydantic>=2
Upgrade
Version history
0.17.0latest on PyPI · released Jan 21, 2026
Audit
Dependencies
pydanticrequiredRequired; version 1 dropped in 0.17.0, must use pydantic 2.x.