Installing Mosquitto MQTT broker on Raspberry Pi (with websockets)

This post describes the steps I used to set up the Mosquitto MQTT broker (server) with websockets enabled on a Raspberry Pi .

This can provide two-way communication between Python programs and JavaScript.

For example:

A python program can send a message and have JavaScript update part of a web page in a way that is similar to AJAX.

A button on a web page can cause JavaScript to send a message telling  Python to run a function or method.

A JavaScript example: MQTT With Websockets and HTML

Updated November 2 2016
Things have changed quite a bit since this post was first written(August 2015). After receiving a comment that the instructions were not working I went through the installation process and found that it is now much quicker and easier.

There is a Debian repository with the latest Mosquito binary which has been compiled with websockets enabled out of the box.

The instructions which follow have been completely updated and have been tested by installing the Mosquitto MQTT broker on a Raspberry Pi running Raspbian Jessie but should also work on other Debian systems

The first few steps are for adding the Mosquitto Debian repository to your system. They are taken directly from the Mosquitto blog post and are reproduced here (with slight modifications) to keep everything in one place.

To use the new repository you should first import the repository package signing key.

sudo apt-key add mosquitto-repo.gpg.key

To make the repository available to apt:

cd /etc/apt/sources.list.d/

Then do one of the following, depending on which version of debian you are using.

sudo wget
sudo wget

Update apt information.

sudo apt-get update

Install Mosquitto:

sudo apt-get install mosquitto

Enabling websockets

In order to enable websockets you will need to edit a Mosquitto configuration file. There is a default config file located at:


It contains some basic settings and it is best to leave this file as-is. It contains comments that say to “Place your local configuration in /etc/mosquitto/conf.d/”  It refers to a file at:


However, I found the file at that location was a gziped file.

Unzip the example file:

 sudo gunzip /usr/share/doc/mosquitto/examples/mosquitto.conf.gz

copy the unziped file to the location indicated in the default config file:

sudo cp /usr/share/doc/mosquitto/examples/mosquitto.conf /etc/mosquitto/conf.d/mosquitto.conf

Edit mosquitto.conf

The mosquitto config file is where most of the settings that control mosquitto’s behavior, including security features, live.

It is necessary to change some settings in order for Python and JaveScript to communicate.

Open the mosquitto config file in your favorite text editor

sudo editor /etc/mosquitto/conf.d/mosquitto.conf

As you scroll down through the file you will see many settings. I changed the following (mostly by removing the leading # to uncomment the setting):

line ~43: user mosquitto

The following settings are for the Python (default) client.

line ~133: bind_address
line ~136: port 1883
line ~151: protocol mqtt

The following settings under Extra listeners are for the JavaScript client.

line ~277: listener 9001
line ~297: protocol websockets


If you will be using mosquitto to build a web based UI, you can have it also act as a web server for your pages.

line ~301: http_dir /usr/share/mosquitto/www

Create the directory for  the web files:

sudo mkdir -p  /usr/share/mosquitto/www

Place your HTML, CSS and Javascript files (or a symlink to them) in the www directory.

Note: having the same settings in both the default config. file and the local config file seems to cause a conflict that prevents mosquitto from starting. Also, if there is more that one space between a setting name and it’s value, the file won’t load.

Get and set up systemd unit file from GitHub

The following instructions include the installation of a systemd unit file in place of the older init.d script which is used with Raspbian Wheezy. The older init.d script is included  with the Mosquitto installation. While the newer systemd which is used in Raspbian Jessie is backward compatible with the init.d script, the systemd unit file is much simpler and more efficient. these steps can also be considered optional.

If you are running Raspbian light you may need to install Git. You can do so with:

sudo apt-get install git

First disable the init.d script:

sudo update-rc.d mosquitto remove


sudo git clone

copy the mosquitto.service file

sudo cp mosquitto_unit_file/mosquitto.service /etc/systemd/system/mosquitto.service

Enable the service

sudo systemctl enable mosquitto.service

After a reboot you can use:

sudo systemctl status | stop | start | restart mosquitto

to control the mosquitto daemon. This is extremely useful when editing and testing the mosquitto.conf file.

The systemd unit file also tells mosquitto which config file to use. Otherwise the mosquitto daemon uses defalult settings which won’t work for our intended purpose. You can test mosquitto using the default settings with:

mosquitto -h

This will tell you the version of mosquitto you are running.

That’s it!

I did not set up any security or other options but it is a good idea to read through the file to learn what is available.

Notes on usage:

Python and JavaScript MQTT client software is required and can be downloaded from the Paho project. See related post Building a browser based User Interface with MQTT

The Python client communicates with the mosquitto broker using the default MQTT protocol and port 1883.

The JavaScript client communicates with the mosquitto broker using the websockets protocol and a port such as 9001 .

A common mistake is to try and use port 9001 from Python. This will cause Python to hang without raising an exception and can be hard to debug.



  1. Init process didn’t work for me.
    When I’d try to stop and start the service; it did work, so I decided to change couple of things:
    1)change init default: “update-rc.d mosquitto disable”
    2)add cron job to start this service after one minute each reboot:
    “sudo crontab -e”
    add the this line to the bottom:
    “@reboot sleep 60 && sudo /etc/init.d/mosquitto start &”

  2. also mosquitto_pub and mosquitto_sub don’t work after following these steps. You’d need to copy to /lib directory:
    cp /usr/local/lib/ /lib
    and also:
    cp /usr/local/lib/ /lib

  3. This problem resulted from using an older style init script on Raspbian Jessie. The solution was to write a systemd unit file as described in the follow up post “Insights from building an MQTT based User Interface”

  4. This following did not work:


    it ended up in a loop reporting errors…

    I am assuming there is an update. (what appears on the libwebsockets website is version 2.1). But not sure how to reconfigure the wget statement to download…

    I am new to the Linux/RaspPi world so it would be great if there was an update. to this..

    Thanks for the instructions… I am able to get mosquito installed and communicating via mosquito_pub and mosquitto_sub and python scripts.. But unable to get it to communicate to a Node.Js or any other HTML page for that matter…

    It would be nice to see a turtorial showing from a fresh image of NOOBS v2_0_0 how to install and setup the Raspberry pi so that mosquito and websockets would work on a local intranet (server being the Raspberry Pi) serving a web page that showed messages from an MQTT broker provided by the Raspberry Pi.. Much of the information I have been able to find is outdated and does not work..

    Thanks in advance…

    1. Thanks for reporting this problem.
      I will work through the process and update the post shortly.

      The post “Insights from building an MQTT based User Interface” has some information about running mosquitto as a web server on a Raspberry Pi. During the time since I wrote that post I have developed a more efficient method of communication between JavaScript and a Python program running on the Pi. I will be posting about that in the next few weeks.


      Edit: The post has been updated. Let me know if you are still having problems getting it to work.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: