Install & Compatibility
Where this runs
tested against v0.46.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 2.009s · 52.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.4s · import 1.875s · 54MB
53MB installed
● package 53MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ControllerApplication
✓ from bellows.zigbee.application import ControllerApplication
Main application class for controlling a Zigbee network via EZSP.
EZSP
✓ from bellows.ezsp import EZSP
Represents the EZSP protocol interface for communication with the Zigbee coordinator.
This quickstart demonstrates how to initialize the `bellows` library to connect to a Zigbee coordinator and start a Zigbee network. It requires a serial port where your EZSP-compatible Zigbee adapter is connected. The `asyncio` event loop is essential for `bellows` operations. Remember to replace the placeholder serial port with your actual device path.
import asyncio
from bellows.ezsp import EZSP
from bellows.zigbee.application import ControllerApplication
async def main():
# Replace '/dev/ttyUSB0' with your serial port, e.g., 'COM3' on Windows
# and adjust baudrate if necessary (default 115200)
# For real use, ensure database_file is persistent.
serial_port = os.environ.get('BELLOWS_SERIAL_PORT', '/dev/ttyUSB0')
database_file = os.environ.get('BELLOWS_DATABASE_FILE', 'zigbee.db')
print(f"Connecting to {serial_port} and using database {database_file}")
try:
ezsp = await EZSP.probe_and_connect(serial_port, 115200)
application = ControllerApplication(ezsp, database_file)
await application.startup(auto_form=True)
print("Zigbee network started successfully!")
# Keep the application running, e.g., for event listening or CLI interaction
while True:
await asyncio.sleep(3600) # Keep alive indefinitely
except Exception as e:
print(f"Error during Zigbee application startup: {e}")
finally:
if 'application' in locals() and application.state.running: # Check if application was successfully started and is still running
await application.shutdown()
print("Zigbee application shut down.")
if __name__ == '__main__':
import os
# Example of setting environment variables for demonstration
# os.environ['BELLOWS_SERIAL_PORT'] = '/dev/ttyUSB0'
# os.environ['BELLOWS_DATABASE_FILE'] = '/tmp/my_zigbee_network.db'
asyncio.run(main())
bellows --version
Errors
Common errors & fixes
Error: Missing option "-d" / "--device".
When using `bellows` CLI commands (e.g., `bellows devices` or `bellows form`), the serial port for the Zigbee adapter was not specified.
fixAlways provide the serial device path using the `-d` or `--device` option, e.g., `bellows -d /dev/ttyUSB0 devices` or `bellows --device COM3 form`.
sqlite3.OperationalError: unable to open database file
The `bellows` application or CLI could not create or access its Zigbee database file, often due to permission issues or an invalid path.
fixEnsure the directory where the database file is intended to be created has write permissions for the user running the `bellows` application. If specifying a path, ensure it is valid and accessible, e.g., `bellows -d /dev/ttyUSB0 form --database /opt/zigbee/zigbee.db`.
AttributeError: 'list' object has no attribute 'split'
This error occurs when running the `bellows scan` command without specifying channels, particularly in older versions or specific environments.
fixExplicitly provide the channels to scan, e.g., `bellows -d /dev/ttyUSB0 scan -c 11 15 20 25` to scan specific Zigbee channels.
NCP EZSP protocol version of XX does not match Host version YY
The EZSP protocol version implemented by the firmware on your Zigbee coordinator (NCP) does not match the version expected or supported by the `bellows` library (Host).
fixUpgrade or downgrade the firmware on your Zigbee coordinator to match the EZSP protocol version required by your `bellows` installation, or check if an older `bellows` version is compatible with your current firmware.
Upgrade
Version history
0.49.2latest on PyPI · released May 27, 2026
Audit
Dependencies
zigpyrequiredCore Zigbee stack implementation that Bellows integrates with.
async-timeoutrequiredTimeout context manager for asyncio programs.
clickrequiredCommand-Line Interface Creation Kit, used for Bellows CLI.
click-logrequiredLogging integration for Click CLI.
pure-pcapy3requiredPure Python reimplementation of pcapy, possibly for serial capture/analysis.
pyserial-asynciorequiredAsyncio-compatible serial port access.
voluptuousrequiredData validation library.