Install & Compatibility
Where this runs
tested against v0.13.4 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 52.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 6.7s · import 0.000s · 54MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Controller
✓ import zigpy_zigate
✗ from zigpy.application import Controller
This quickstart demonstrates how to initialize a `zigpy` controller with a ZiGate radio. The `zigpy-zigate` library automatically registers the 'zigate' radio type when imported. You need to provide the correct serial port path for your ZiGate device. For Ethernet ZiGate, use a `socket://IP:PORT` format. This example initializes the controller and keeps the event loop running; a real application would then build and manage the Zigbee network.
import asyncio
import os
from zigpy.application import Controller
from zigpy.config import CONF_DEVICE, CONF_DEVICE_PATH, CONF_RADIO_TYPE
# Ensure zigpy-zigate is imported so its radio type is registered
import zigpy_zigate # noqa: F401
async def main():
# Replace '/dev/ttyUSB0' with your ZiGate's serial port
# For PiZiGate, it might be '/dev/serial0' or '/dev/ttyAMA0'
# For ZiGate Ethernet, it would be 'socket://IP_ADDRESS:PORT'
zigate_port = os.environ.get('ZIGATE_PORT', '/dev/ttyUSB0')
config = {
CONF_DEVICE: {
CONF_DEVICE_PATH: zigate_port,
CONF_RADIO_TYPE: 'zigate'
}
}
controller = None
try:
print(f"Initializing zigpy Controller with ZiGate on {zigate_port}...")
controller = await Controller.new(config)
print("Zigbee network initialized. Controller is running.")
# In a real application, you would now interact with the controller
# e.g., controller.add_endpoint(), controller.start_network(), etc.
print("Controller object created. You can now use it to manage your Zigbee network.")
print("Press Ctrl+C to stop.")
await asyncio.Event().wait() # Keep the event loop running indefinitely
except Exception as e:
print(f"Error during zigpy initialization: {e}")
finally:
if controller:
await controller.shutdown()
print("Controller shut down.")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingFuture deprecation within Home Assistant's ZHA integration: An issue was opened in April 2025 to discuss deprecating XBee and ZiGate radio support within the `zigpy/zha` project, which is the primary consumer of `zigpy-zigate`. This indicates a potential future breaking change for users relying on `zigpy-zigate` through Home Assistant ZHA.fixMonitor `zigpy/zha` and `zigpy-zigate` GitHub repositories for official announcements. Consider migrating to a different, actively recommended Zigbee adapter if you rely on ZHA.
affects: Future versions of Home Assistant ZHA (post-April 2025 discussion)
gotchaZiGate Firmware Compatibility: ZiGate hardware requires firmware 3.1a or later to function with `zigpy-zigate`. Firmware 3.1d or later is strongly recommended as it includes critical bug fixes related to `zigpy` compatibility. Using older firmware can lead to unexpected issues or instability.fixEnsure your ZiGate adapter's firmware is updated to at least version 3.1d. `zigpy-zigate` includes an integrated 'flasher' tool for NXP Jennic JN5168 chips. Refer to official ZiGate firmware releases for updates.
affects: < 3.1d firmware on ZiGate hardware
gotchaLimited Feature Support: Some advanced Zigbee features are not supported by ZiGate adapters when used with `zigpy-zigate` and `zigbee-herdsman` (which can also use ZiGate). These include changing the Zigbee channel without re-pairing all devices, adding install codes (required for some devices), full backups, and Inter-PAN communication (required for Touchlink).fixBe aware of these limitations. If your use case requires these specific features, consider a different Zigbee adapter that explicitly supports them.
affects: All versions
Upgrade
Version history
0.14.0latest on PyPI · released Apr 20, 2026
Audit
Dependencies
zigpyrequiredCore Zigbee protocol stack; zigpy-zigate is a radio backend for zigpy.
pyserial-asynciorequiredAsynchronous serial communication with the ZiGate radio.
voluptuousrequiredData validation for configuration.