aiounifi

90 verified Fri May 01 auth: no python

aiounifi is an asynchronous Python library for communicating with the UniFi Network Controller API. It provides a clean async interface for managing UniFi devices, clients, and settings. The current version is 90, requiring Python >=3.13.0, with active development and frequent releases.

pip install aiounifi

Common errors

error aiounifi.exceptions.Unauthorized ↓

cause Invalid credentials or session expired.

fix

Ensure username/password are correct and call await controller.initialize() to re-authenticate.

error aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host 192.168.1.1:8443 ssl:default [getaddrinfo failed] ↓

cause Wrong host or port, or network unreachable.

fix

Check controller IP and port; if using default HTTPS port (8443), ensure it's correct.

error AttributeError: 'Controller' object has no attribute 'login' ↓

cause Code uses deplicated `login()` method removed in newer versions.

fix

Use controller.initialize() instead of controller.login().

Warnings

deprecated The method `controller.login()` is deprecated since v71; use `controller.initialize()` which automatically authenticates. ↓

fix Replace `await controller.login()` with `await controller.initialize()`.

gotcha SSL verification is enabled by default (since v65). Many local controllers use self-signed certificates, causing SSL errors. ↓

fix Set `ssl_verify=False` in Controller constructor or provide a valid SSL context.

breaking Python 3.12 support dropped; requires Python >=3.13 as of version 88. ↓

fix Upgrade Python to 3.13 or higher, or pin aiounifi to <88.

gotcha The `get_clients()` method returns a list of `Client` objects, not raw dicts (changed in v50). ↓

fix Access client attributes like `client.name` instead of `client['name']`.

Imports

Controller
wrong
```
from aiounifi.controller import Controller
```
correct
```
from aiounifi import Controller
```
Controller is exported from the top-level package since v45

Site

wrong

from aiounifi.models.site import Site

correct

from aiounifi import Site

Site model class is available at top-level since v60

Quickstart

Connect to a UniFi controller and list sites.

import asyncio
from aiounifi import Controller

async def main():
    controller = Controller(
        host="192.168.1.1",
        username="admin",
        password="password",
        port=8443,
        ssl_verify=False
    )
    await controller.initialize()
    sites = await controller.get_sites()
    print(sites)
    await controller.close()

asyncio.run(main())