Zigbee2MQTTZigbee2MQTT
  • Getting started
  • Supported Adapters
  • Supported Devices
  • Installation
  • Configuration
  • Usage
  • FAQ
Devices
  • Zigbee

    • Zigbee network
    • Improve network range and stability
    • Secure your Zigbee network
    • Sniff Zigbee traffic
    • Create a CC2530 router
  • Support new devices

    • Support new devices
    • Support new Tuya devices
    • Find Tuya Data Points
  • Remote Adapter

    • Connect to a remote adapter
    • Connect to a remote Sonoff ZBBridge
  • More

    • 3D cases
    • External converters
    • External extensions
    • Switch to the dev branch
    • Get Tuya and Xiaomi OTA url
  • Forum
  • Discord
  • Issues
  • Donate
GitHub
GitHub (docs)
  • Getting started
  • Supported Adapters
  • Supported Devices
  • Installation
  • Configuration
  • Usage
  • FAQ
Devices
  • Zigbee

    • Zigbee network
    • Improve network range and stability
    • Secure your Zigbee network
    • Sniff Zigbee traffic
    • Create a CC2530 router
  • Support new devices

    • Support new devices
    • Support new Tuya devices
    • Find Tuya Data Points
  • Remote Adapter

    • Connect to a remote adapter
    • Connect to a remote Sonoff ZBBridge
  • More

    • 3D cases
    • External converters
    • External extensions
    • Switch to the dev branch
    • Get Tuya and Xiaomi OTA url
  • Forum
  • Discord
  • Issues
  • Donate
GitHub
GitHub (docs)
  • Getting started
  • Supported Hardware
    • Adapters
    • Devices
  • Installation
    • Linux
    • Docker
    • Home Assistant addon
    • openHABian
    • Windows
    • FreeBSD jail
    • Kubernetes
    • Watchdog
    • Zigbee2MQTT fails to start/crashes runtime
  • Configuration
    • Adapter settings
    • MQTT
    • Zigbee network
    • Frontend
    • Devices and Groups
    • Logging
    • Device blocklist / passlist
    • OTA device firmware update
    • Device Availability
    • Home Assistant integration
    • More configuration options
    • Configuration update
  • Usage
    • Allowing devices to join
    • Integrations
    • Touchlink
    • Scenes
    • Binding
    • Groups
    • OTA updates
    • MQTT Topics and Messages
    • Exposes
  • FAQ

Configuration

ATTENTION

Never rely solely on configurations produced by LLMs like ChatGPT! Always verify the generated configurations against the relevant documentation. Not doing so can potentially break your setup.

Zigbee2MQTT is configured using YAML based configuration.yaml file. The file have to be located in the data directory within your installation. The data directory and the configuration.yaml has to be writeable for Zigbee2MQTT process because it can get updated - e.g. if you change the settings in the frontend. It's possible specify a custom data directory by setting the ZIGBEE2MQTT_DATA environment variable.

# Minimal configuration.yml example
permit_join: true
mqtt:
    server: mqtt://localhost:1883
serial:
    # Could be either USB port (/dev/ttyUSB0), network Zigbee adapters (tcp://192.168.1.1:6638) or mDNS adapter (mdns://my-adapter).
    port: /dev/ttyUSB0
# Will run frontend on port 8080
frontend:
    enabled: true

CONVENTION

The dot-notation of a config-key like mqtt.server means server property within the mqtt section. All dot-notation references are absolute.

ATTENTION

Be aware of the implications using permit_join: true and read the details in the Permit join documentation.

Environment variables

It is possible to override the values in configuration.yaml via environment variables. The name of the environment variable should start with ZIGBEE2MQTT_CONFIG_ followed by the path to the property you want to set in uppercase split by a _.

In case you want to for example override:

mqtt:
    base_topic: zigbee2mqtt

set ZIGBEE2MQTT_CONFIG_MQTT_BASE_TOPIC to the desired value.

Config changes at runtime

Some configuration options can be changed at runtime by issuing a MQTT-publish at the topic zigbee2mqtt/bridge/request/options. See MQTT Topics and Messages for details.

Help to make the docu better and edit this page on Github ✌
Last Updated:: 5/16/25, 7:53 PM
Prev
Installation
Next
Adapter settings