python-kasa

0.10.2 verified Fri May 01 auth: no python

Python API for TP-Link Kasa and Tapo smart home devices. Version 0.10.2 supports bulbs, plugs, switches, hubs, cameras, robot vacuums, and more. Active development with frequent releases.

pip install python-kasa

Common errors

error AttributeError: module 'kasa' has no attribute 'Discover' ↓

cause Importing from a wrong location or using too old version (<0.4.0).

fix

Use from kasa import Discover and upgrade python-kasa: pip install --upgrade python-kasa.

error RuntimeError: asyncio.run() cannot be called from a running event loop ↓

cause Trying to run async code inside an already running loop (e.g., Jupyter or script already async).

fix

Use await directly if already in async context, or use nest_asyncio.apply() for Jupyter.

error kasa.exceptions.SmartDeviceException: Authentication failed ↓

cause Invalid credentials or Tapo account has two-factor authentication enabled.

fix

Ensure credentials are correct and use an app password if 2FA is on. For some devices, use the local IP-based discovery without credentials.

error kasa.exceptions.TimeoutError: Timed out ↓

cause Device not reachable on the network or firewall blocking.

fix

Verify device IP and network connectivity. Ensure you are on the same subnet.

Warnings

breaking Python 3.11 is now required (requires_python >=3.11). Python 3.9 and 3.10 no longer supported. ↓

fix Upgrade Python to 3.11 or later.

breaking Tapo cloud credentials are required for newer Tapo devices (Tapo protocol). Old Kasa devices may also need credentials depending on firmware. `Discover.discover()` with no credentials will find fewer devices. ↓

fix Pass a `Credentials` object with email and password to `Discover.discover()`.

gotcha Asynchronous API: all methods are async. You must use `asyncio.run()` or await inside an async context. ↓

fix Wrap code in `async def main(): ... asyncio.run(main())`.

deprecated Direct import from `kasa.smart` or `kasa.iot` submodules is discouraged. Use top-level `kasa.SmartDevice` or `kasa.IotDevice` instead. ↓

fix Import from `kasa` directly: `from kasa import SmartDevice`.

gotcha Device update may fail if a child device (e.g., plug on a hub) reports unsupported data. Ensure you run the latest version. ↓

fix Upgrade to >=0.8.1.

Imports

Discover
wrong
```
from kasa.discover import Discover
```
correct
```
from kasa import Discover
```
Discover is exposed at the top-level kasa module since v0.4.0
Device
wrong
```
from kasa.device import Device
```
correct
```
from kasa import Device
```
Device is exposed at the top-level kasa module

SmartDevice

wrong

from kasa.smart import SmartDevice

correct

from kasa import SmartDevice

SmartDevice is exported from kasa directly

Quickstart

Discover all Kasa/Tapo devices on the network using credentials.

import asyncio
from kasa import Discover, Credentials

async def main():
    creds = Credentials(username='email@example.com', password='password123')
    devices = await Discover.discover(credentials=creds)
    for ip, dev in devices.items():
        print(f'{ip}: {dev.alias} ({dev.model})')

asyncio.run(main())