zha-quirks

What it is and what it does

zha-quirks is a library of custom device handlers for the Zigpy Zigbee library, designed to make non-standard Zigbee devices work correctly with Home Assistant's ZHA component. Many Zigbee devices deviate from the Zigbee Cluster Library specification, and this package bridges that gap by implementing device-specific quirks that parse custom messages and handle manufacturer deviations.

The package works by defining virtual representations of physical Zigbee devices (light bulbs, switches, sensors, etc.) that expose functionality not provided out-of-the-box. It handles endpoints, clusters, and descriptors according to Zigbee specifications, allowing Home Assistant to correctly communicate with devices that would otherwise be incompatible or non-functional. The package is actively maintained and includes support for common manufacturers like Tuya.

Use it for:

• Enable non-standard Zigbee light bulbs or switches to work with Home Assistant's ZHA integration.
• Add support for Tuya Zigbee devices that use custom manufacturer-specific clusters.
• Handle Zigbee devices that do not fully conform to the ZCL specification.
• Extend Home Assistant's Zigbee device compatibility without modifying the core ZHA component.
• Contribute new device handlers for previously unsupported Zigbee devices.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides custom device handlers (quirks) for non-standard Zigbee devices to work with the ZHA component in Home Assistant via the Zigpy library.

Yes, if you are running Home Assistant with ZHA and have non-standard Zigbee devices. The package is actively maintained, has no known vulnerabilities, and uses a permissive license. Install friction is low. If you are not using Home Assistant or ZHA, this package is not applicable.

Install

zha-quirks on PyPI

pip install zha-quirks

uv add zha-quirks

poetry add zha-quirks

Installing zha-quirks

Before you install

Low install friction with a pure Python wheel. The package is actively maintained with a recent release and steady commit activity. Requires Python 3.12 or later.

License in practice

Licensed under Apache-2.0 (permissive), allowing free use, modification, and distribution with minimal restrictions.

Quickstart

pip install zha-quirks

from zha_quirks import get_quirked_device
# Used internally by ZHA integration in Home Assistant

Requires Python 3.12 or later. Intended for use within Home Assistant's ZHA component, not as a standalone library.

Verify before relying

• Whether the package is intended for direct end-user installation or primarily for Home Assistant maintainers and contributors.
• The scope and number of device handlers currently included in version 2.2.0.
• Whether custom quirks can be added or extended by end users without modifying the package itself.

Package facts

Evidence: zha_quirks-2.2.0-py3-none-any.whl

Tags

More Application Frameworks packages