Install & Compatibility
Where this runs
tested against v0.84.0 · 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 1.654s · 52.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 6.3s · import 1.534s · 54MB
53MB installed
● package 53MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ControllerApplication
✓ from zigpy.application import ControllerApplication
✗ from zigpy.app import ControllerApplication
The `zigpy.app` module was renamed to `zigpy.application` in zigpy 1.0.0.
CONF_DEVICE
✓ from zigpy.config import CONF_DEVICE
ZCL_CLUSTER_TYPE
✓ import zigpy.zcl.clusters as ZCL_CLUSTER_TYPE
Commonly imported as an alias for convenience when working with ZCL clusters.
This quickstart demonstrates how to initialize and start a `zigpy` application. It attempts to connect to a Zigbee coordinator specified by `ZIGBEE_DEVICE_PATH` and `ZIGBEE_DEVICE_BAUDRATE` environment variables (defaulting to '/dev/ttyUSB0' and 115200). Note that this example requires a physical Zigbee coordinator and a corresponding `zigpy` adapter library (e.g., `zigpy-znp`) to run successfully. Without a device, it will raise an exception.
import asyncio
import logging
import os
from zigpy.application import ControllerApplication
from zigpy.config import CONF_DATABASE_PATH, CONF_DEVICE, CONF_DEVICE_PATH, CONF_DEVICE_BAUDRATE
logging.basicConfig(level=logging.INFO)
async def run_zigbee_app():
# In a real scenario, the device path would be your Zigbee coordinator's path
# (e.g., '/dev/ttyUSB0' on Linux, 'COM3' on Windows) and its baudrate.
# For this quickstart without a physical device, it will likely fail to connect.
# Replace with valid device path and baudrate for successful execution with hardware.
config = {
CONF_DATABASE_PATH: "zigbee_quickstart.db",
CONF_DEVICE: {
CONF_DEVICE_PATH: os.environ.get("ZIGBEE_DEVICE_PATH", "/dev/ttyUSB0"),
CONF_DEVICE_BAUDRATE: int(os.environ.get("ZIGBEE_DEVICE_BAUDRATE", "115200")),
}
}
print(f"Attempting to start zigpy application with device: {config[CONF_DEVICE][CONF_DEVICE_PATH]}")
app = None # Initialize app to None
try:
# Initialize the Zigbee controller application
# auto_form=True will form a new network if one doesn't exist
# auto_backup=True will manage database backups
app = await ControllerApplication.new(
config=config, auto_form=True, auto_backup=True
)
print("Zigbee application initialized. Starting up...")
await app.startup(auto_form=True) # Start the network connection
print("Zigbee application started. Press Ctrl+C to stop.")
print("In a real application, you'd have event listeners, device discovery, etc. here.")
# Keep the application running for a short period or until interrupted
await asyncio.sleep(60)
except Exception as e:
logging.error(f"Failed to start zigpy application: {e}")
print("\nError: Ensure your Zigbee coordinator is connected and path/baudrate are correct.")
print("You may need to install an adapter library (e.g., 'pip install zigpy-znp') for your hardware.")
finally:
if app and app.state.started:
print("\nShutting down Zigbee application...")
await app.shutdown()
print("Application shut down.")
if __name__ == "__main__":
asyncio.run(run_zigbee_app())
Debug
Known issues
breakingMajor architectural changes were introduced in zigpy 1.0.0, including the renaming of the `zigpy.app` module to `zigpy.application` and the removal of `zigpy.state` and `zigpy.util` modules. Code written for pre-1.0 versions will require updates.fixUpdate imports from `zigpy.app` to `zigpy.application`. Review migration guides for other changes (e.g., state management, utility functions).
affects: <1.0.0
gotchazigpy is a low-level Zigbee stack library and requires a specific hardware adapter (Zigbee coordinator) to function. You must install a separate `zigpy-` plugin package (e.g., `zigpy-znp`, `zigpy-deconz`, `zigpy-zigate`) corresponding to your coordinator hardware.fixIdentify your Zigbee coordinator model and install the appropriate `zigpy-` adapter library (e.g., `pip install zigpy-znp`). Ensure the coordinator is properly connected and its serial path/baudrate are correctly configured.
affects: All versions
gotchazigpy versions >=1.1.0 officially require Python 3.11 or newer. While earlier Python 3.x versions might work with older zigpy releases, it's recommended to use the specified Python version for full compatibility and access to the latest features and bug fixes.fixUpgrade your Python environment to 3.11 or newer to ensure full compatibility and support for the latest zigpy features.
affects: <1.1.0 (for older Python versions), All versions (for Python 3.11+ requirement)
gotchazigpy is an asynchronous library built on `asyncio`. All interactions with the `ControllerApplication` and other core components must be performed within an `async` context and run by an `asyncio` event loop.fixEnsure your application's entry point uses `asyncio.run()` and all zigpy-related calls are `await`ed within `async def` functions.
affects: All versions
Errors
Common errors & fixes
serial.serialutil.SerialException: [Errno 13] Permission denied: '/dev/ttyUSB0'
The user account running the zigpy application lacks the necessary permissions to access the specified serial port device.
fixAdd the user to the `dialout` group (on Linux) with `sudo usermod -a -G dialout $USER` and reboot, or ensure the port is not in use by another application and has correct permissions.
ModuleNotFoundError: No module named 'zigpy_deconz'
The specific zigpy radio backend library required for your hardware adapter (e.g., ConBee/RaspBee) has not been installed.
fixInstall the appropriate backend library using pip, for example, `pip install zigpy-deconz` for ConBee/RaspBee adapters, or `pip install zigpy-cc` for CC2531/CC2652 adapters.
No backend handler found for specified path
zigpy could not find or load a compatible radio backend driver for the specified serial port or adapter configuration, possibly due to a missing backend or incorrect path.
fixEnsure the correct zigpy radio backend library is installed (e.g., `pip install zigpy-cc`) and that the serial port path and adapter type in your configuration are accurate.
SyntaxError: invalid syntax
The Python interpreter version being used is older than the minimum required Python 3.8 for zigpy, leading to syntax errors for newer language features.
fixUpgrade your Python installation to version 3.8 or higher, or activate a virtual environment configured with a compatible Python version.
RuntimeError: There is no current event loop in thread 'MainThread'.
zigpy is an asyncio-based library and requires an active asyncio event loop, but its asynchronous operations were called outside an `async` context or without `asyncio.run()`.
fixStart your zigpy application's main async function using `asyncio.run(main_async_function())` or ensure zigpy calls are made within an existing `asyncio` event loop.
Upgrade
Version history
2.1.0latest on PyPI · released Jul 28, 2026
Audit
Dependencies
pyserialrequiredRequired for serial communication with most Zigbee coordinators.
zigpy-znpoptionalAn adapter library specific to your Zigbee coordinator hardware. This is an example, you need to install the correct adapter for your device.