How to install Zigbee2MQTT on Unraid

Using this guide you can learn how exactly to install Zigbee2MQTT on your Unraid server using Docker

Disclosure: This post contains affiliate links. If you click through and make a purchase, I’ll earn a commission, at no additional cost to you. Read my full disclosure here.

Zigbee2MQTT is a popular piece of software with which you can replace just about any Zigbee hub out there with a single solution. You can connect Philips Hue, IKEA TRÅDFRI, Aqara and many more devices from different vendors to it and manage your Zigbee network from one all-encompassing location.

The Zigbee2MQTT logo
The Zigbee2MQTT logo

Be for starting the configuration you will need a Zigbee adapter for Zigbee2MQTT to be able to communicate with the sensors and devices. That adapter has to be directly connected to your Unraid server. The recommended options are the Electrolama zig-a-zig-ah! and Slaesh’s CC2652RB stick. I went for the latter as Germany is a neighbouring country of Switzerland and thus the delivery didn’t take too long. I will personally recommend Slaesh’s CC2652RB stick without without a second’s hesitation.

The Texas Instruments CC2531 is most likely the cheapest adapter and was, until recently, the recommended option. However, you need a CC debugger and CC2531 downloader cable to accompany it, which does push the price up. The CC2531 is no longer recommend by the applications author as it supports fewer simultaneously connected devices when compared to newer adapters, and it only has a PCB antenna which doesn’t have the best range. Despite not being recommended, the CC2531 is still supported alongside a handful of other adapters.

Zigbee2MQTT best practices

There are a few rules I recommend you follow when setting up Zigbee2MQTT on Unraid (and any other system for that matter) and your Zigbee network in general. Firstly, get yourself a USB female to male extension cable and create some distance between the Zigbee adapter and the Unraid server. If you were to plug the adapter in to one of the onboard USB ports, the antenna can suffer from interference stemming from radio signals and electrical components of the Unraid server.

Secondly, don’t place the adapter anywhere near a Wi-Fi router or access point. Wi-Fi and Zigbee both operate in the 2.4 GHz spectrum and interference between the two is a common occurrence (with Zigbee usually losing out). I also recommend you take a look at this article and set your Zigbee and Wi-Fi channels accordingly.

If you want to increase the range and stability of your Zigbee network, buy more routers. Almost any mains-powered device is also a router which will relay messages from other devices. If you’re struggling with range, buy yourself more Zigbee lights or smart outlets and place them around your place.

Finding the path to the Zigbee adapter

The only slightly complicated part of installing Zigbee2MQTT on Unraid is finding the adapter’s path. Linux does not assign USB drives a driver letter and instead mounts them somewhere in the /dev folder. With the Zigbee adapter plugged in to your Unraid server, open the terminal and execute the run the following command:

The icon symbolising the Unraid terminal
Open the terminal by clicking on this icon
ls -l /dev/serial/by-id

The answer to this command should read similar to the one shown below. As you can see, I use Slaesh’s CC2652RB stick and the device is named accordingly. That way I can be sure to have the right path. The path you will need is highlighted in blue. Copy it and paste it into a note as you will need it during the installation of Zigbee2MQTT on Unraid.

lrwxrwxrwx 1 root root 13 Feb 19 09:54 usb-Silicon_Labs_slae.sh_cc2652rb_stick_-_slaesh_s_iot_stuff_00_12_4B_00_21_CC_4B_DF-if00-port0 -> ../../ttyUSB0

I recommend mapping the adapter using this method, especially if you have multiple USB devices attached to your Unraid server. While there is another way of mapping the adapter, I don’t see any advantage of choosing that option over the one described above.

Installing Zigbee2MQTT on Unraid

There is a preconfigured template for Zigbee2MQTT available in the Unraid Community Applications. It is provided by the Selfhosters Unraid Discord Repository and is the preferred way of installing Zigbee2MQTT on Unraid. You could set up a virtual machine and host it natively, but Docker does speed things up and the configuration is much easier.

Searching for Zigbee2MQTT in Unraid’s Community Applications should bring up the correct Docker container template and nothing else. You can customize the containers name if you so wish (I see no reason to do so), and I recommend leaving the network type set to bridge mode.

The only setting that has to be adjusted is the path to your Zigbee adapter. Here you will want to enter /dev/serial/by-id followed by the path you looked up earlier (and should have copied in a note, if you listened to me). For my setup, the complete path looks like this:


Configuring Zigbee2MQTT

Once you start the container you will either be greeted by an error or it will stop running immediately. This is to be expected and is no reason to worry. If your container is still running but throwing up errors, you can manually stop it.

What happened during this first start is that the appropriate file structure and configuration file were created. Use an editor such as code-server to access Zigbee2MQTT’s persistent storage on Unraid. If you used the template without making any adjustments other than setting the path to the adapter, you will find it under /mnt/user/appdata/Zigbee2MQTT/.

Configuring the MQTT server

In that folder you will find a configuration file (configuration.yaml), which needs to be edited. First you will have to enter your MQTT server’s info. You can leave the base topic set to zigbee2mqtt, but the server, username, and password will need to be filled in.

  base_topic: zigbee2mqtt
  server: 'mqtt://'
  user: <MY_MQTT_USER>

Configuring the Zigbee adapter port

You will once again have to configure the path that was entered in the Docker container’s configuration file in to the configuration.yaml file. This will tell Zigbee2MQTT exactly where it has to look for the Zigbee adapter.

  port: >-

This step might seem redundant to you, but once you think about it, it makes perfect sense. The mapping we did in the container only gave the Zigbee2MQTT access to the adapter, in the configuration file we have to tell Zigbee2MQTT where it can be found.

Further adjustments to Zigbee2MQTT

While you have the configuration file open, you may as well finish wrap this up by choosing your Zigbee channel (follow the guide I linked earlier on) and create a network key for more security.

  channel: 25
  network_key: GENERATE

With the configuration complete, you can start the container and begin adding your Zigbee devices to your new Zigbee network running on your Unraid server. Should you encounter any issues, there are extensive guides available on the official Zigbee2MQTT website and there is also a Zigbee2MQTT discourse group where any questions will be answered by the helpful community.

About Liam Alexander Colman

I first heard of Unraid through the same medium as many of us did: The Linus Tech Tips channel on YouTube. At the time, I was running TrueNAS (or FreeNAS as it was called back then) on my DIY NAS built using a dual-core Intel Pentium G4400 at its heart. I was convinced, I had chosen the better operating system. After all, it was free and open-source and had a large community behind it. One day, after once again facing the need to buy another three hard drives, I seriously started researching Unraid and its features. I bit the bullet and gave it a go, transferring my data on to external hard drives that I later shucked and added to the Unraid array. Since that day, I have not looked back once, and I am now an enthusiastic and experienced user of Unraid. You can find out more about Unraid Guides right here.

Leave a comment