Install & Compatibility
Where this runs
tested against v0.0.112 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 55.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.5s · import 0.000s · 57MB
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Device
✓ from zhaquirks import CustomDevice
✗ from zigpy.quirks import Device
This quickstart demonstrates the structure for creating a custom ZHA quirk, which is the primary way developers interact with this library's capabilities. This Python code defines a device quirk class that Home Assistant's ZHA integration (via `zigpy`) can automatically discover and load. The code itself is not meant to be run standalone to 'do' something directly, but rather to be integrated into a Home Assistant setup as a module. Replace `MyManufacturer`, `MyTempSensor`, and cluster definitions with your device's actual signature and desired behavior.
import logging
from zigpy.profiles import zha
from zigpy.quirks import CustomCluster, Device
from zigpy.zcl.clusters.general import Basic, Identify
from zigpy.zcl.clusters.measurement import TemperatureMeasurement
_LOGGER = logging.getLogger(__name__)
class MyCustomTemperatureCluster(CustomCluster, TemperatureMeasurement):
cluster_id = TemperatureMeasurement.cluster_id
# Add any specific attributes or commands for this custom cluster if necessary
class MyCustomDeviceQuirk(Device):
"""Custom quirk for a hypothetical MyManufacturer Temp Sensor."""
signature = {
# The 'signature' must exactly match the device's reported model_id and manufacturer.
# This determines if the quirk is applied to a discovered device.
"model_id": "MyTempSensor",
"manufacturer": "MyManufacturer",
# Endpoint configuration is defined in 'replacement', not directly in 'signature'.
}
replacement = {
1: zha.Endpoint(
profile_id=zha.PROFILE_ID,
device_type=zha.DeviceType.TEMPERATURE_SENSOR,
input_clusters=[
Basic.cluster_id,
MyCustomTemperatureCluster, # Use your custom cluster or a standard one
Identify.cluster_id,
],
output_clusters=[]
)
}
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
_LOGGER.info(f"MyCustomDeviceQuirk detected: {self.model_id} from {self.manufacturer}")
# To make this quirk functional within Home Assistant's ZHA integration:
# 1. Save this code as a .py file (e.g., `my_custom_sensor.py`) in a dedicated directory,
# for example, `/config/custom_zha_quirks/` within your Home Assistant configuration.
# 2. Add the following to your Home Assistant `configuration.yaml`:
# `zha:
# custom_quirks_path: /config/custom_zha_quirks/`
# 3. Restart Home Assistant.
# 4. If the device was previously paired, you might need to 'Reconfigure device' from its
# ZHA device page or, in some cases, remove and re-pair the device to apply the quirk.
# Replace `MyManufacturer`, `MyTempSensor`, and cluster definitions with your device's actual details.
Debug
Known issues
breakingStrict Python version requirements. Ensure your Python environment meets the requirements for the installed `zha-quirks` version.fixUpgrade your Python environment to the version required by `zha-quirks` and Home Assistant, or install a compatible `zha-quirks` version if downgrading Python is not an option. Check `requires_python` in PyPI metadata.
affects: All versions (e.g., <1.1.1 required 3.8+, 3.10+; 1.1.1 requires >=3.12)
gotcha`zha-quirks` is an extension for `zigpy`. Ensure `zigpy` is also up-to-date and compatible with both `zha-quirks` and your Home Assistant version, as incompatibilities can lead to ZHA instability or device recognition failures.fixRegularly update `zha-quirks` and `zigpy` together, typically by updating Home Assistant itself if using the core integration. If manually installing or managing a virtual environment, ensure `pip install --upgrade zha-quirks zigpy`.
affects: All versions
gotchaAfter installing `zha-quirks` or adding/modifying custom quirks, existing paired devices might not immediately pick up the new quirk due to ZHA caching device information.fixRestart Home Assistant. If the device still isn't recognized, try 'Reconfigure device' from the ZHA device page in Home Assistant or, as a last resort, remove and re-pair the device. For custom quirks, also ensure `custom_quirks_path` is correctly configured in `configuration.yaml`.
affects: All versions
gotchaDevice signatures (manufacturer and model ID) in a custom quirk definition must *exactly* match what the physical device reports during discovery for the quirk to be applied.fixVerify the device's signature from the ZHA integration's device info (e.g., from 'Manage Clusters' under 'Basic' cluster attributes) and ensure your custom quirk's `signature` dictionary matches it precisely, including case sensitivity.
affects: All versions
Upgrade
Version history
1.2.0latest on PyPI · released Apr 29, 2026
Audit
Dependencies
zigpyrequiredCore dependency for Zigbee protocol and device handling.