Installing Zigbee2MQTT on Linux


When working with Home Assistant supervised or HassOS, it is advisable to use the addon HassIO Zigbee2MQTT Addon instead of the installation method described below.

This installation option is for installing the Zigbee2MQTT service on a computer or on JetHome JetHub controllers. The up-to-date instructions for installing Zigbee2MQTT on a Linux computer can be found on the Zigbee2MQTT Linux installation guide project page.


To operate Zigbee2MQTT, you must first install an MQTT broker, such as mosquitto:

sudo apt install -y mosquitto mosquitto-clients

When MQTT is installed, the broker will be set to start automatically and run. You can check the status of the service with the command:

sudo systemctl status mosquitto.service

The Zigbee2MQTT requires node.js version at least 16.x. Install the additional packages required for the build as well:

sudo apt-get update
sudo curl -fsSL | sudo -E bash -
sudo apt-get install -y nodejs git make g++ gcc

Download the source code of Zigbee2MQTT:

sudo mkdir /opt/zigbee2mqtt
sudo chown -R ${USER}: /opt/zigbee2mqtt
git clone --depth 1 /opt/zigbee2mqtt


cd /opt/zigbee2mqtt
npm ci

Make changes to the configuration file:

nano /opt/zigbee2mqtt/data/configuration.yaml

Approximate contents of the configuration file:

# Home Assistant integration (MQTT discovery)
homeassistant: true

# Allow new devices to join
permit_join: false

# MQTT settings
  # MQTT base topic for Zigbee2MQTT MQTT messages
  base_topic: zigbee2mqtt
  # MQTT server URL
  server: 'mqtt://localhost'

# Serial settings
  # Location of CC2538 Zigbee module for JetHub H1
  port: /dev/ttyAML2

# Optional: advanced settings
  # Optional: ZigBee channel (Note: changing requires re-pairing of all devices)
  channel: 15
  # Optional: ZigBee pan ID
  pan_id: 0x1a62
  # Optional: network encryption key, will improve security (Note: changing requires repairing of all devices)
  network_key: [1, 3, 5, 7, 9, 11, 13, 15, 0, 2, 4, 6, 8, 10, 12, 13]

  # Optional, default 8080
  port: 8080
  # Optional, default


  • The example shows the port name for the JetHub H1 controller (/dev/ttyAML2) for other controllers or USB sticks the port name may be different (see your device documentation).

  • The default values shown are pan_id and network_key. It is recommended that you set other values for these parameters.

Manual start

cd /opt/zigbee2mqtt
npm start

Automatic start

To start Zigbee2MQTT automatically at system startup, a file must be created:

sudo nano /etc/systemd/system/zigbee2mqtt.service

File Contents:


ExecStart=/usr/bin/npm start


where <USER> is the user name under which the installation was performed.

Activate and run the service:

sudo systemctl enable zigbee2mqtt.service
sudo systemctl start zigbee2mqtt.service

After starting the service, you can check the logs to make sure it is working:

sudo journalctl -u zigbee2mqtt.service -f

Possible problems

Error: Failed to connect to the adapter (Error: SRSP - SYS - ping after 6000ms)

Unable to connect to a Zigbee adapter (built-in Zigbee module, USB stick). Possible reasons for this error:

  • The port to which the Zigbee adapter is connected is incorrect. Specify the correct port for your device in the configuration file

  • The Zigbee adapter contains incorrect coordinator firmware or the firmware is damaged. You need to write coordinator firmware to the Zigbee adapter for this device

  • The Zigbee adapter is already in use by another application (e.g. Home Assistant ZHA). You must disable other applications that can use Zigbee

Error: Error while opening serialport ‘Error: Error: Permission denied, cannot open /dev/ttyAML2’

The user who installed and ran Zigbee2MQTT has no access rights to the serial port where the Zigbee adapter is connected.

The user under which Zigbee2MQTT is started must be included in the dialout group:

sudo gpasswd --add ${USER} dialout

Then log out and log in again as this user.


Other possible problems when starting Zigbee2MQTT and how to solve them are described in the project documentation Zigbee2MQTT Fails to start.