TL;DR
Create a folder under /config/, set it as custom_quirks_path under zha: in configuration.yaml, drop the Python quirk file into that folder, and restart Home Assistant.
If nothing changes afterwards: remove and re-pair the device - many quirks only take effect during the device interview.

Why “Quirks” at all?

ZHA does a solid job for devices that follow Zigbee specs closely. The problem: not every device does - and many advanced features are hidden behind manufacturer-specific clusters.

That’s what ZHA Device Handlers (a.k.a. zha-quirks / “quirks”) are for: small Python modules that can

• correctly identify devices,
• translate clusters/attributes,
• expose extra entities,
• apply workarounds for vendor oddities.

If a quirk is not merged upstream (yet), you can still use it locally in Home Assistant - that’s exactly what this page covers.

Prerequisites

• You run Home Assistant with the ZHA integration.
• You can edit files in your HA config directory (/config/), for example via:
  • File Editor / Studio Code Server add-on,
  • Samba/SMB share,
  • SSH / terminal.
• You can restart Home Assistant.

Step-by-step: Install custom ZHA quirks

You only need three things: a folder under /config/, a single line in configuration.yaml, and the quirk .py file.

1) Create a folder for your local quirks

Pick any name you like. Example:

1

/config/custom_zha_quirks/

2) Point ZHA to that folder

Open configuration.yaml and add (or extend) the zha: block:

1
2

zha:
  custom_quirks_path: /config/custom_zha_quirks

3) Drop the quirk file into the folder

Save the quirk as a .py file, e.g.:

1

/config/custom_zha_quirks/aqara_fp300.py

4) Restart Home Assistant

Use Settings → System → Restart (or a full restart, depending on your setup).

⚠️ Important: Remove & re-pair the device if needed

If you don’t see new entities or any behavior changes after restarting Home Assistant, the quirk may not have been applied yet. In that case, force a clean re-interview:

1. 🗑️ Remove the device from ZHA
2. 🔄 Factory reset the device (if applicable)
3. 🔗 Pair it again

✅ It’s a bit annoying — but it’s often the decisive step. Many quirks hook into the initial device interview, so a restart alone may not be enough.

Install Aqara FP300 Custom Quirk

The Aqara FP300 is a great real-world example of why custom quirks matter. Out of the box, ZHA can only do so much if a device relies on vendor-specific behavior or exposes capabilities in a way that isn’t mapped yet. A dedicated quirk bridges that gap by teaching ZHA how to interpret the device correctly and by surfacing the right entities in Home Assistant.

For the FP300, I created a quirk and submitted it upstream as a pull request to the official ZHA Device Handlers repository (zha-device-handlers / zha-quirks). The goal of that PR is to add official FP300 support so everyone gets a clean experience without manual steps. The PR is currently in review (open PR #4504) — and even once it’s merged, it can still take some time until the changes land in a released zha-quirks version and Home Assistant updates the dependency in a stable release. In other words: “merged” doesn’t always mean “available in your HA install today”.

That’s where custom quirks are useful: you can use the same quirk code locally right now, and later switch back to upstream/built-in support once it’s part of the mainline and shipped with Home Assistant.

If you want to follow the progress or join the discussion, start with the tracking issue (FP300 support issue #4487) and the PR linked above (review state, changes, test feedback). If you just want to use it immediately, the quirk code is available as a copy/paste-friendly file (FP300 quirk Gist). And if you’re still deciding whether the FP300 is worth it, my hands-on covers the device in more detail (FP300 hands-on / review).

How to use the FP300 quirk locally

1. Copy the quirk from the Gist into /config/custom_zha_quirks/ as aqara_fp300.py
2. Restart Home Assistant
3. If you don’t see changes: remove & re-pair the FP300 (see above)

FAQ

How do I Rollback and Remove a custom quirk

1. Delete (or rename) the .py file inside your custom_quirks_path.
2. Restart Home Assistant.
3. If you want a “clean” state: remove & re-pair the device so it gets interviewed without the quirk.

To verify you’re truly “without quirk”, enable debug logging briefly and check for zhaquirks matching messages.

Do I need to set enable_quirks?

In most setups quirks are enabled by default. If you want to be explicit:

1
2
3

zha:
  enable_quirks: true
  custom_quirks_path: /config/custom_zha_quirks

Does this work in Home Assistant Container?

Yes — as long as your config volume is mounted to /config/ and your quirk folder lives there.

Can I override built-in quirks with this?

Yes. custom_quirks_path is loaded in addition to built-in quirks, and a matching custom quirk can take precedence (as long as the device signature matches).