{"id":24296,"library":"pyatv","title":"pyatv","description":"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.","status":"active","version":"0.17.0","language":"python","source_language":"en","source_url":"https://github.com/postlund/pyatv","tags":["apple-tv","airplay","home-assistant","mrp","companion"],"install":[{"cmd":"pip install pyatv","lang":"bash","label":"Latest stable"}],"dependencies":[{"reason":"Required; version 1 dropped in 0.17.0, must use pydantic 2.x.","package":"pydantic","optional":false}],"imports":[{"note":"","wrong":"","symbol":"pyatv","correct":"import pyatv"},{"note":"scan is a top-level function, not in pyatv.core.","wrong":"from pyatv.core import scan","symbol":"scan","correct":"from pyatv import scan"},{"note":"The correct way is to use pyatv.connect.","wrong":"from pyatv import interface","symbol":"connect","correct":"from pyatv import connect"},{"note":"top-level module, import as shown.","wrong":"import pyatv.const","symbol":"const","correct":"from pyatv import const"}],"quickstart":{"code":"import asyncio\nfrom pyatv import scan, connect\n\nasync def example():\n    devices = await scan(loop=asyncio.get_running_loop(), timeout=5)\n    if not devices:\n        print(\"No Apple TV found\")\n        return\n    atv = devices[0]\n    print(f\"Found: {atv.name} at {atv.address}\")\n    try:\n        conn = await connect(atv, loop=asyncio.get_running_loop())\n        print(\"Connected successfully\")\n        # Example: play/pause\n        await conn.remote_control.play_pause()\n        conn.close()\n    except Exception as e:\n        print(f\"Connection failed: {e}\")\n\nasyncio.run(example())","lang":"python","description":"Scan for Apple TV devices, connect to the first one found, and send a play/pause command."},"warnings":[{"fix":"Run: pip install 'pydantic>=2'","message":"In 0.17.0, support for pydantic v1 was dropped. You must have pydantic 2.x installed.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Upgrade Python to 3.9 or later.","message":"Python 3.9+ required. Python 3.8 support dropped in 0.16.0.","severity":"breaking","affected_versions":">=0.16.0"},{"fix":"If you relied on imghdr, reimplement using other means.","message":"The `imghdr` module (via mediafile) was removed in 0.16.0. The library now uses tinytag for metadata.","severity":"deprecated","affected_versions":">=0.16.0"},{"fix":"Ensure you are using at least pyatv 0.16.1.","message":"On tvOS 18.4+, connection may fail. Fixed in 0.16.1 but still may appear.","severity":"gotcha","affected_versions":">=0.7.0"},{"fix":"Upgrade pyatv to 0.14.4+ or wrap coroutines in asyncio.create_task.","message":"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.","severity":"gotcha","affected_versions":">=3.11, <0.14.4"},{"fix":"Use `import pyatv` and access submodules like `pyatv.const`.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Upgrade pyatv: pip install --upgrade pyatv","cause":"Outdated version of pyatv (pre-0.7.0) where scan was not a public top-level function.","error":"ImportError: cannot import name 'scan' from 'pyatv'"},{"fix":"Upgrade to pyatv 0.14.2 or later.","cause":"Known issue in pyatv <0.14.2 where TimeoutError during connection was incorrectly re-raised as AuthenticationError, causing frequent reconfiguration in Home Assistant.","error":"RuntimeError: TimeoutError raised as AuthenticationError"},{"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.","cause":"Trying to use pyatv functions without async/await context or passing coroutines to asyncio.wait incorrectly.","error":"TypeError: object dict can't be used in 'await' expression"},{"fix":"Install both pyatv and pydantic: pip install pyatv pydantic>=2","cause":"pydantic is a required dependency missing from the environment.","error":"ModuleNotFoundError: No module named 'pydantic'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}