aiohasupervisor is an asynchronous Python client designed for interfacing with the Home Assistant Supervisor's REST API. It is currently at version 0.4.3 and is actively maintained, with a release cadence tied to the development and releases of Home Assistant itself, as it's primarily used within the Home Assistant ecosystem, particularly by its Supervisor integration and add-ons.
Install & Compatibility
Where this runs
tested against v0.3.3 · 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.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SupervisorClient
✓ from aiohasupervisor import SupervisorClient
✗ from aiohasupervisor.client import Client
This quickstart demonstrates how to initialize the `aiohasupervisor` client and fetch basic supervisor information. It expects the `SUPERVISOR_TOKEN` environment variable to be set, which is automatically handled when running as a Home Assistant add-on. For external development, the `SUPERVISOR_API_URL` should also be set, and a token obtained from the `remote_api` add-on.
import asyncio
import os
from aiohasupervisor.client import Client
async def get_supervisor_info():
# The SUPERVISOR_TOKEN environment variable is automatically set for Home Assistant add-ons.
# For remote development/testing, use the remote_api add-on to get a token and set SUPERVISOR_API_URL.
supervisor_token = os.environ.get('SUPERVISOR_TOKEN', 'YOUR_SUPERVISOR_TOKEN')
supervisor_api_url = os.environ.get('SUPERVISOR_API_URL', 'http://supervisor/core') # Default for add-ons
if supervisor_token == 'YOUR_SUPERVISOR_TOKEN':
print("Warning: SUPERVISOR_TOKEN not set. This example may not work without a valid token.")
print("Please refer to the aiohasupervisor GitHub for development setup with remote_api add-on.")
return
async with Client(supervisor_api_url, supervisor_token) as client:
try:
info = await client.info()
print("Supervisor Info:", info)
except Exception as e:
print(f"Error fetching Supervisor info: {e}")
if __name__ == "__main__":
asyncio.run(get_supervisor_info())
Debug
Known issues
breakingThe `IngressPanel` class was removed from `aiohasupervisor.models`. Home Assistant Core installations (especially venv) starting from 2026.4 might fail to start if they incorrectly try to import this class via the `hassio` integration.fixFor Home Assistant Core venv installations, either modify `addon_panel.py` to handle the `IngressPanel` import gracefully (e.g., with a try-except block) or create an empty `custom_component/hassio/__init__.py` to prevent the `hassio` integration from loading.
affects: aiohasupervisor versions used by Home Assistant Core 2026.4+
gotchaThe library heavily relies on `SUPERVISOR_TOKEN` and optionally `SUPERVISOR_API_URL` environment variables for authentication and endpoint discovery. Without these, the client cannot connect to the Home Assistant Supervisor.fixEnsure `SUPERVISOR_TOKEN` is set (automatically in add-ons, manually from `remote_api` for development). For remote access, set `SUPERVISOR_API_URL` to your Home Assistant instance's IP.
affects: All versions
deprecatedOlder versions of `aiohasupervisor` (e.g., 0.2.2b5) were sometimes included as pre-release dependencies in Home Assistant Core, causing issues with dependency resolvers like `uv`.fixEnsure `aiohasupervisor` is updated to a stable release version. If encountering resolution issues with Home Assistant Core, try using `--prerelease=allow` with your package manager as a temporary workaround, though a proper fix involves stable dependency versions.
affects: Prior to 0.3.x, specifically 0.2.2b5 and related pre-releases.
Audit
Dependencies
No dependency data recorded yet.