ZHA quirk database

A quirk teaches ZHA how a device that does not follow the Zigbee standard really behaves – without one, a Tuya thermostat or an Aqara sensor often shows up with missing or wrong entities. For every device you see the quirk to use and where it comes from: one that ships with ZHA, one proposed but not merged yet, or a custom quirk people shared in the issue tracker.

737devices with a quirk in ZHA
637proposed
123custom quirks

637 devices found

Using a custom quirk

  1. Tell ZHA where custom quirks are kept – in configuration.yaml: 
    zha:
  custom_quirks_path: /config/custom_zha_quirks/
  2. Create that folder and save the quirk as a .py file in it.
  3. Restart Home Assistant. If the device was paired before, reconfigure it or remove and pair it again so the quirk is applied.
  4. Check it worked: the device page shows the quirk under Zigbee info.

A custom quirk has not been reviewed by the ZHA maintainers. Delete the file once the quirk is part of a Home Assistant release – otherwise the old copy takes precedence.

Sources: zha-device-handlers on GitHub – the latest release, its open pull requests and issues. Only which devices a quirk applies to, which entities it adds, who shared it and how many people agreed are read; the code stays on GitHub. The recommendation prefers a quirk that ships with ZHA, then a proposed one, then the custom quirk with the most approvals.

Scroll to Top