# zigpy is a hardware independent Zigbee stack in Python

> zigpy implements the Zigbee protocol stack as a Python 3 library, with the vendor specific work delegated to separate radio libraries for Ember, deCONZ, XBee, Z-Stack and ZiGate hardware. It suits home automation developers who want one API across coordinators, and it inherits every quirk of the radio it is paired with.

**zigpy/zigpy** — Library implementing a Zigbee stack

- Repository: https://github.com/zigpy/zigpy
- Stars: 1,068 · Forks: 217
- Language: Python
- License: GPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/zigpy-zigpy

## The protocol stack without the radio

zigpy is a hardware independent Zigbee protocol stack written in Python 3, implementing the Zigbee standard specifications. The hardware independence is the organising idea, and the readme is explicit about how it is achieved. The stack and hardware from many different chip manufacturers are supported through radio libraries, which translate each vendor's proprietary communication protocol into a common API shared among all of them.

The division of labour is clean. zigpy contains the common code that implements ZCL, the Zigbee Cluster Library, and ZDO, the Zigbee Device Object, application state management. The radio libraries implement the actual interface to the radio modules, and they talk to the hardware adapters over USB and GPIO using different native UART serial protocols. So the state machine lives in one place, and the vendor peculiarities live in separate repositories with their own release cycles.

That split is also why a new coordinator can be supported without touching zigpy. If some vendor's hardware is not supported yet, an independent developer can write a new radio library that translates that protocol into the common API, and the rest of the stack stays as it is.

The audience is a developer writing a home automation integration. The readme names three projects that depend on the zigpy libraries: the ZHA integration component for Home Assistant, the Zigbee plugin for Domoticz and the Zigbee plugin for Jeedom, and it suggests them as references for how to integrate Zigbee into an application. The project also carries a badge from the Open Home Foundation, and the licence is GPL-3.0.

## Which coordinator hardware is actually supported

The radio libraries are listed with the hardware they cover, and this is the part to check before designing around a coordinator.

For Digi XBee based radios there is zigpy-xbee, for dresden elektronik deCONZ based radios there is zigpy-deconz, for Silicon Labs EmberZNet based radios using the EZSP protocol there is bellows, for Texas Instruments radios with compatible Z-Stack firmware there is zigpy-znp, and for ZiGate based radios there is zigpy-zigate. One entry is marked as legacy or obsolete, which is zigpy-cc for Texas Instruments with legacy Z-Stack firmware, and it is worth knowing about before you plan a product around that path.

Zigbee 3.0 support is where the readme puts the emphasis on reading the hardware documentation rather than trusting the software. Support depends primarily on the coordinator hardware and its firmware. Some coordinators support Zigbee 3.0 but ship with older firmware that does not, in which case you may want to upgrade the firmware yourself. Other coordinators have no firmware capable of Zigbee 3.0 at all, and can still be fully functional and feature complete for what you need, which the readme notes is very common since many devices do not yet use Zigbee 3.0 or are backwards compatible with a profile your coordinator already supports. As a general rule, newer coordinator hardware can normally support Zigbee 3.0 firmware, and it is up to the manufacturer to make that firmware available.

The device types zigpy can control cover the usual home automation categories: binary sensors such as motion and door sensors, temperature sensors, lights, switches, buttons, covers, fans, climate control equipment, locks and intruder alarm system devices.

## ZCL and ZDO state, and the one gap

The core of the library is state management for the two Zigbee application layers, and the readme describes the supported device set in the same breath as the one gap, which is worth stating early. Zigbee Green Power devices are currently unsupported, with an issue tracking that work.

Green Power is the part of the Zigbee specification aimed at ultra-low power devices, typically battery operated switches and sensors that can act without a mains powered device nearby. If a product's device list includes that class, zigpy cannot cover it today, and the tracking issue is the place to see whether that has changed.

The rest of the device list, binary sensors, temperature sensors, lights, switches, buttons, covers, fans, climate equipment, locks and intruder alarm devices, is broad enough that most of a home automation installation falls inside it. The interesting part is that the coverage is not a per-device-model list. It is a list of device types and the clusters they use, so a temperature sensor from any vendor is handled by the same cluster implementation, and the vendor differences are the radio's problem rather than the stack's.

For firmware, there is a further layer the readme mentions. The Zigbee OTA update image files have to conform to the standard Zigbee OTA format, and the OTA provider source URLs have to be published for public availability, which is a constraint imposed by the manufacturers rather than by zigpy.

## Over the air updates, and the five providers that work

zigpy can download and perform Zigbee OTAU firmware updates on devices, and it can do so from a local directory as well, which is the option for offline updates if you supply correctly formatted firmware files yourself. The offline path is worth knowing about in any deployment where devices sit on a private network, since it removes the dependency on the vendor's servers and on the public availability of the image URLs.

Automatic download from online OTA providers is currently available for a specific set of manufacturers: IKEA, Inovelli, LEDVANCE/OSRAM, SONOFF/ITEAD and ThirdReality, also written as 3reality. That is the practical limit on automatic updates today, and the readme explains the condition for widening it. Support for further manufacturers could be added if the device makers publish their firmware images publicly and developers contribute the download code.

The condition is worth reading carefully, because it explains why the list is short. Zigpy does not host firmware. It fetches images that a manufacturer has made public, using URLs the manufacturer publishes, and the provider code for each brand has to be written by someone. So the growth path for OTA coverage is upstream, in the manufacturers' publishing policies, with the code following.

There is a second constraint in the same paragraph that applies to every update. The images must conform to the standard Zigbee OTA format, and the source URLs have to be publicly available. A manufacturer that keeps both of those closed cannot be added, no matter how willing the community is.

## The package metadata and what a dependency looks like

The project metadata says a lot about how the library is built and tested. The package is zigpy, the version is derived from the git tags through setuptools-git-versioning, and the build requires Python 3.11 or later. The runtime dependencies are aiohttp for network access, aiosqlite for the application database, cryptography for the security primitives, crccheck for checksums, voluptuous and jsonschema for validation, serialx for serial ports, attrs and frozendict for data structures, and typing_extensions.

```toml
requires-python = ">=3.11"
dependencies = [
    "attrs",
    "aiohttp",
    "aiosqlite>=0.20.0,<0.22.0",
    "crccheck",
    "cryptography",
    "voluptuous",
    "jsonschema",
    "serialx>=1.4.0",
    "typing_extensions",
    "frozendict",
]
```

The testing group is unusually detailed, which says something about how the project treats regressions. It pins mypy at 1.19.1 and ruff at 0.14.14, uses pytest with pytest-asyncio in auto mode, and includes coverage, coveralls, freezegun for time-dependent tests and codespell. One entry is a compatibility constraint with a comment explaining it: aioresponses 0.7.8 is incompatible with aiohttp 3.14's mandatory stream_writer argument, so aiohttp is held below 3.14 until the upstream pull request is released. That kind of pinned workaround is what a project with a large test suite accumulates.

The ruff configuration targets py311 with a line length of 88, and the pre-commit configuration in the repository root runs the same linters before a commit lands. The tree also carries a script directory, tools, tests and the zigpy package itself, and the schema files for the application database are shipped as package data.

## Releases, branches and where to look for help

The release record shows a project moving on a short cycle. Version 2.3.0 was published on 2026-09-29, 2.2.0 on 2026-09-07 and 2.1.0 on 2026-07-28, and the last push was on 2026-10-12. The default branch is dev, which is where the CI badge and the coverage badge point, and the release tags come out of that branch.

The licence is GPL-3.0, recorded both in the project metadata and in the COPYING file at the root of the repository. For a library that several home automation platforms embed, that is the part of the package to read before shipping a commercial product on top of it, and the readme's own note about how to contribute says to follow the guidelines in CONTRIBUTING.md for installing and testing the project, for troubleshooting and bug reporting, and for the library and code instructions for developers.

That file is also where the practical answers live. The readme describes it as containing information about using zigpy, testing new releases, troubleshooting, bug reporting, and summaries with links to other projects that depend on zigpy libraries directly or indirectly. The readme also states the three ways to contribute: as an end user, as a tester who files constructive issue reports, or as a developer who contributes code.

The distinction between the stack and the radio libraries is worth keeping in mind when you read any of that. A bug in a device that misbehaves after an update may well live in the radio library rather than in zigpy, and each library has its own repository and its own maintainers.

## Where a vendor stack or a platform integration fits better

There are two sensible alternatives, and they suit different situations.

The first is the platform integration. If you are building a home automation system rather than a home automation platform, using ZHA in Home Assistant, the Domoticz plugin or the Jeedom plugin gives you a working Zigbee implementation maintained by somebody else. The readme suggests exactly this, and points at those three projects as references. zigpy is the library under them, so choosing the platform does not lock you out of the library, it only changes who maintains the parts you did not want to write.

The second is the vendor's own stack. A manufacturer of the coordinator or the device usually ships tooling that talks to their hardware directly, with their device behaviour guaranteed and their firmware updates handled by their servers. Where a product is single-vendor and the device list is closed, that path is less work and fewer surprises.

The difference in approach is where the abstraction sits. zigpy puts the Zigbee specification in Python and treats the radio as a detail behind a common API, which means one integration can be moved between coordinators by changing the radio library. A vendor stack puts the abstraction around one vendor's world, which is simpler within that world and expensive outside it.

The reason to prefer zigpy over a vendor stack is portability across coordinators, and the reason to prefer the vendor is device coverage certainty. And if you are building a platform rather than an installation, the deciding factor is that zigpy gives you the state machine and lets you own the rest, which is exactly what ZHA, Domoticz and Jeedom did.

## Conclusion

zigpy fits developers building a home automation integration that has to run on more than one coordinator, and teams that want the Zigbee state machine in Python rather than in a vendor's closed tooling. It does not fit a product that needs a device class zigpy has not implemented, since Green Power devices are currently unsupported. Verify first that a radio library exists for the coordinator you plan to ship with, that its firmware is new enough for the Zigbee features you need, and that the OTA provider for your device brands is one of the five the project supports today.

## FAQ

### What is zigpy and what does it not cover?

zigpy is a hardware independent implementation of the Zigbee protocol stack as a Python 3 library, handling ZCL and ZDO state management. The hardware side is delegated to separate radio libraries, and Zigbee Green Power devices are currently unsupported.

### Which Zigbee radios can zigpy talk to?

Radio libraries exist for Digi XBee through zigpy-xbee, dresden elektronik deCONZ through zigpy-deconz, Silicon Labs EmberZNet over EZSP through bellows, Texas Instruments Z-Stack through zigpy-znp, and ZiGate through zigpy-zigate. The legacy Texas Instruments path is zigpy-cc, which the readme lists as obsolete.

### Does zigpy support Zigbee 3.0?

That depends on the coordinator hardware and its firmware rather than on zigpy. Some coordinators support Zigbee 3.0 but ship with older firmware, some cannot support it at all yet remain functional, and for newer hardware the manufacturer has to make the firmware available.

### Which manufacturers can zigpy update over the air?

Automatic download from online OTA providers currently works for IKEA, Inovelli, LEDVANCE/OSRAM, SONOFF/ITEAD and ThirdReality devices. Offline updates from a local directory of correctly formatted firmware files are also supported, and more providers can be added once manufacturers publish their images and developers contribute the download code.

## Sources

- [Issues](https://github.com/zigpy/zigpy/issues)
- [License: GPL-3.0](https://github.com/zigpy/zigpy/blob/dev/LICENSE)
- [README](https://github.com/zigpy/zigpy/blob/dev/README.md)
- [Releases](https://github.com/zigpy/zigpy/releases)
- [zigpy/zigpy on GitHub](https://github.com/zigpy/zigpy)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zigpy-zigpy