Install & Compatibility
Where this runs
tested against v0.14.2 · 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 · 52.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.3s · import 0.000s · 54MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ZnpApplication
✓ from zigpy_znp import ZnpApplication
✗ from zigpy_znp import ZnpApplication
This quickstart demonstrates how to initialize a `zigpy` controller using `zigpy-znp` as the radio backend. It sets up a basic configuration, attempts to start the controller, and optionally forms a new Zigbee network. Remember to replace `/dev/ttyUSB0` with your actual serial port and ensure you have the necessary permissions.
import asyncio
import os
from zigpy.application import Controller
from zigpy.config import CONF_DATABASE_PATH, CONF_DEVICE, CONF_RADIO_TYPE
async def main():
# Replace with your actual serial port for the ZNP radio
# On Linux: '/dev/ttyACM0' or '/dev/ttyUSB0'
# On Windows: 'COM3'
serial_port = os.environ.get("ZNP_SERIAL_PORT", "/dev/ttyUSB0")
# Define the zigpy configuration
config = {
CONF_DEVICE: {
CONF_RADIO_TYPE: "znp", # This activates zigpy-znp
"port": serial_port,
},
CONF_DATABASE_PATH: "zigpy_znp.db", # Database for network state
}
print(f"Starting zigpy controller with ZNP radio on {serial_port}...")
controller = Controller(config)
try:
# auto_form=True creates a new network if none exists. Set to False if you expect to join an existing network.
await controller.startup(auto_form=True)
print("Controller started successfully. Network formed/joined.")
# At this point, you can interact with the Zigbee network, e.g., discover devices
print("Controller running for 10 seconds. Press Ctrl+C to stop sooner.")
await asyncio.sleep(10) # Keep running for 10 seconds
print("Shutting down controller.")
except Exception as e:
print(f"Error starting controller: {e}")
finally:
await controller.shutdown()
print("Controller shut down.")
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Exiting.")
Debug
Known issues
gotchaOn Linux, users often encounter 'Permission denied' errors when accessing serial ports (`/dev/ttyACM0` or `/dev/ttyUSB0`).fixAdd your user to the `dialout` group (e.g., `sudo usermod -a -G dialout $USER`) and reboot or log out/in. Ensure correct udev rules are applied if using a custom device.
affects: All versions
gotchaIncompatible ZNP firmware versions on your TI radio can lead to connection issues, instability, or missing features.fixEnsure your ZNP radio is flashed with a compatible and recent firmware. Refer to the `zigpy-znp` documentation or community resources for recommended firmware versions for your specific hardware (e.g., CC2531, CC2652P).
affects: All versions, depending on hardware firmware
gotchaOnly one application can access a serial port at a time. Trying to run multiple instances of `zigpy` or other serial tools simultaneously will cause errors.fixEnsure no other programs (e.g., Home Assistant, another `zigpy` instance, a serial terminal) are using the specified serial port before starting your `zigpy-znp` application. Check for zombie processes.
affects: All versions
breakingChanges in the core `zigpy` library's API or configuration scheme can affect `zigpy-znp` users, as `zigpy-znp` is a radio backend for `zigpy`.fixAlways check the release notes for `zigpy` itself when upgrading `zigpy-znp` or `zigpy`. Update your `zigpy` configuration (`CONF_DEVICE`, `CONF_DATABASE_PATH`, etc.) as per `zigpy`'s latest documentation.
affects: Dependent on `zigpy` major version bumps (e.g., zigpy 0.x to 0.y)
Upgrade
Version history
1.1.0latest on PyPI · released May 31, 2026
Audit
Dependencies
zigpyrequiredCore Zigbee application framework which zigpy-znp extends.
pyserial-asynciorequiredProvides asynchronous serial communication capabilities required to talk to the ZNP radio.
crcmodrequiredUsed for CRC (Cyclic Redundancy Check) calculations, essential for the ZNP protocol's data integrity.