Home Assistant CHIP Clusters

2025.7.0 verified Fri May 01 auth: no python

Python bindings for CHIP (Connected Home over IP) clusters, auto-generated from the CHIP specification. Version 2025.7.0 requires Python >=3.7 and provides cluster objects for interacting with Matter devices. Released monthly alongside the CHIP SDK.

pip install home-assistant-chip-clusters

Common errors

error ModuleNotFoundError: No module named 'home_assistant_chip_clusters' ↓

cause Wrong import path; the package is installed as 'chip-clusters' but imported as 'chip.clusters'.

fix

Change import to 'from chip.clusters import ...'.

error AttributeError: module 'chip' has no attribute 'clusters' ↓

cause The required subpackages were not installed or the import fails because 'chip' is not a namespace package.

fix

Run 'pip install home-assistant-chip-clusters' again and ensure you use 'from chip.clusters import ...'.

error ImportError: cannot import name 'Clusters' from 'chip' ↓

cause Trying to import 'Clusters' directly from the top-level 'chip' module instead of 'chip.clusters'.

fix

Use 'from chip.clusters import Clusters'.

Warnings

gotcha The package name on PyPI is 'home-assistant-chip-clusters' but the import path is 'chip.clusters' (not 'home_assistant_chip_clusters'). ↓

fix Use 'from chip.clusters import ...' in your code.

breaking In v2025.7.0 some cluster attribute IDs may have changed due to spec updates. Rely on the Attributes object rather than hardcoded IDs. ↓

fix Use Clusters.OnOff.attributes.OnOff.attribute_id instead of integer literals.

deprecated The 'Clusters' module is generated automatically; manual editing of cluster definitions is overwritten on pip upgrade. ↓

fix Do not modify files under site-packages/chip/clusters/. Fork or patch via hooks.

Imports

Clusters
wrong
```
import home_assistant_chip_clusters
```
correct
```
from chip.clusters import Clusters
```
The package is installed as 'chip-clusters' but the import is from 'chip.clusters'.
Objects
wrong
```
from chip import Clusters
```
correct
```
from chip.clusters import Objects
```
The Objects module is nested under chip.clusters.

Quickstart

Create a cluster instance and access its attributes.

from chip.clusters import Clusters, Objects
cluster = Clusters.OnOff()
print(cluster.cluster_id)  # 6