Configuration

Zigbee2MQTT is configured using YAMLopen in new window based configuration.yml file. The file have to be located in the data directory within your installation. The data directory and the configuration.yml 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:
  base_topic: zigbee2mqtt
serial:
  port: /dev/ttyUSB0
frontend:
  port: 8080
1
2
3
4
5
6
7
8

CONVENTION

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

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
1
2

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.