python-kasa for Local Control of Kasa and Tapo Devices

Why python-kasa Exists for Kasa and Tapo Automation

python-kasa is aimed at developers who need to control supported TP-Link Kasa and Tapo smart home devices from Python or a terminal instead of relying solely on a vendor application. The documented device categories include plugs, wall switches, power strips, and bulbs, with Tapo support identified in the package description. Its repository topics also include `asyncio`, `kasa`, `tapo`, and `tplink`, matching the library's position as an asynchronous Python integration.

The project is community driven and explicitly says it is not affiliated with, sponsored by, or endorsed by TPLink. That distinction matters for product selection. python-kasa is not presented as an official cloud API or as a replacement for every function available through TP-Link's cloud-connected services. Its practical appeal is direct programmatic access to device operations such as power state, brightness, color temperature, light effects, presets, and smooth transitions.

The intended users are Python developers building home automation, monitoring, or device-specific tooling. The `kasa` command also makes the library useful for manual administration. In both cases, the device must expose a supported protocol and be reachable from the controlling machine. The README does not promise universal compatibility with every Kasa or Tapo product.

Discovery, Authentication, and Device Communication

Discovery is network based. Running `kasa discover` sends discovery packets to the default broadcast address, `255.255.255.255`, for three seconds. It then runs the `state` command against each discovered device, which means discovery also produces an initial state report rather than merely listing hostnames.

A supported device that requires authentication needs a username and password. The CLI accepts `--username` and `--password`, while `KASA_USERNAME` and `KASA_PASSWORD` provide environment variables. On a machine with several network interfaces, `--target` selects the broadcast address. This matters because an unrestricted or incorrect broadcast path can prevent discovery even when the device is healthy on another local network segment.

For hub-connected devices, control requests also need the connected device's identifier. The README's example passes that identifier through the feature command with `--child`. The architecture therefore has two distinct addressing layers: the host identifies the reachable hub or device, while the child ID selects the device attached through it.

Installing python-kasa and Running a First Device Command

The documented installation for normal use is a PyPI package install. This installs the library, its dependencies, and the `kasa` command declared by the project.

pip install python-kasa

After installation, discover devices on the local network:

kasa discover

The output starts with the broadcast address and discovery duration, then prints device details and state for each supported device found. Authenticated devices can instead receive credentials through `--username` and `--password`, or through `KASA_USERNAME` and `KASA_PASSWORD`.

For a discovered device, switch it on by supplying its host and the `on` command:

kasa --host 192.0.2.123 on

That is the smallest useful first use because it exercises discovery or host identification, connection, authentication if required, and a device command without requiring application code.

Using the Async Python API in an Application

The library API is asynchronous and exposes convenience methods on a discovered device object. The README example connects to one host with `Discover.discover_single`, turns it on, and calls `update` to refresh its state.

import asyncio
from kasa import Discover

async def main():
    dev = await Discover.discover_single("192.0.2.123", username="[email protected]", password="pw")
    await dev.turn_on()
    await dev.update()

if __name__ == "__main__":
    asyncio.run(main())

The application passes the host, username, and password to discovery, then issues awaited device operations. This model fits Python applications already built around `asyncio`, including services that need to coordinate polling and control with other network tasks. It also makes error handling part of the caller's asynchronous flow, rather than presenting a synchronous API.

The repository declares Python `>=3.11,<4.0` and lists classifiers for Python 3.11 through 3.14. Applications on older Python versions cannot use this release according to `pyproject.toml`.

Generic Features Versus Device-Specific Commands

python-kasa offers two documented interaction styles. The first is the convenience API shown by methods such as `turn_on()` and `update()`. The second is the generic feature interface exposed through `kasa feature`. The feature listing groups controls under categories such as primary features, information, configuration, and debug.

A bulb may expose state, brightness, color temperature, and light effects. Its configuration may include HSV values, light presets, and separate smooth-transition settings. A feature can be changed through its feature name and value:

kasa --host 192.0.2.123 feature color_temperature 2500

The output reports the previous value, the requested value, and the new state. This generic approach is useful when software must inspect and control capabilities without hard-coding one command shape per product. It also makes unsupported or unavailable features visible by omission rather than hiding every device behind a single abstraction.

The trade-off is that callers still need device-specific interpretation. Feature names, valid ranges, and child identifiers vary by hardware. The convenience methods are clearer for known devices, while the feature interface is the more general option for heterogeneous collections.

CLI Inspection and Hub-Connected Device Control

The CLI is not limited to switching power. `kasa --help` lists available commands and options, and the README identifies `--json`, `--verbose`, `--timeout`, and `--discovery-timeout`. Individual commands can have additional options that are visible through their own `--help` output. This gives operators both human-readable state inspection and machine-readable output without moving every task into Python.

The generic feature command is also the clearest path for supported settings that do not have a common top-level command. For a device reached through a hub, the host addresses the hub and `--child` addresses the connected device:

kasa --host 192.0.2.200 feature --child someuniqueidentifier target_temperature 21

The example changes `target_temperature` to 21. It also demonstrates why a simple host scan is insufficient for some installations. Device discovery, hub routing, and feature availability form separate concerns.

The repository contains a `SUPPORTED.md` file, and its contribution guide asks for fixture files when device hardware or firmware is not listed as supported. That repository structure treats compatibility as device-specific and test-data dependent. Documentation examples should therefore be treated as patterns, not proof that an arbitrary Kasa or Tapo model will work.

License, Compatibility, and Maintenance Boundaries

The package metadata identifies the license as `GPL-3.0-or-later`, using the OSI license identifier `GNU General Public License v3 or later (GPLv3+)`. The repository summary labels it as a custom license that GitHub cannot classify and points to the `LICENSE` file. Anyone integrating the code into a distributed product should inspect that file directly for its actual obligations. This review does not interpret the license terms.

Release 0.11.0.1 is the most recent listed release, dated 2026-10-04. The repository's last push was on 2026-10-14. The project is not archived, but recent repository activity alone does not guarantee support for every device or firmware combination.

Upgrade cost depends on the Python version and device coverage. The current package requires Python 3.11 or later and supports classifiers through Python 3.14. Moving from an earlier python-kasa release may also require checking API changes, while adding a new device can involve the broader support status and fixture-based testing process. Optional dependency groups include `speedups`, which adds `orjson>=3.11.1` and `kasa-crypt>=0.2.0`, and `shell`, which adds `ptpython` and `rich`.

Editorial conclusion

Adopt python-kasa when an application needs local, scriptable control of a device listed as supported and the required host, credentials, and network broadcast path are acceptable. Do not choose it as a universal replacement for TP-Link services, especially for unsupported models or environments that cannot reach devices directly. Check SUPPORTED.md, confirm the device responds on the intended network, and verify the credential flow before integrating device control into a larger application.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. python-kasa/python-kasa on GitHub
4. README
5. Releases