---
id: zha-quirks
version: "2.2.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# zha-quirks — Library implementing Zigpy quirks for ZHA in Home Assistant

License: permissive · Maintenance: active · Downloads: 338.5K/mo

## 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 above — 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

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

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 338.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

zigbee device handlers home assistant, zha quirks zigpy, custom zigbee device support, zigbee non-standard device support, zha device compatibility, zigbee cluster library quirks, home assistant zigbee customization, home-assistant, zigbee, iot

[View on SkillFed](https://skillfed.io/packages/zha-quirks) · [View on PyPI](https://pypi.org/project/zha-quirks/)