by stlehmann

stlehmann / Flask-MQTT

Flask Extension for the MQTT protocol

140 Stars 46 Forks Last release: 6 months ago (1.1.1) MIT License 196 Commits 16 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:


Flask Extension for the MQTT protocol. Basically it is a thin wrapper around paho-mqtt and aims to simplify MQTT integration in Flask. MQTT is a machine-to-machine "Internet of Things" protocol and was designed for extremely lightweight publish/subscribe messaging transport.

Documentation Status PyPI version Travis CI Coverage Status Anaconda-Server Badge Downloads Downloads

Find the documentation on http://flask-mqtt.readthedocs.io.


  • configuration via Flask config variables
  • auto-connect on start of your web application
  • publish and subscribe messages
  • use callbacks for certain topics
  • use one callback for all subscribed topics


Flask-MQTT was developed to provide an easy-to-setup solution for interacting with IoT devices. A typical scenario would be a Raspberry Pi running a mosquitto mqtt server combined with a Flask webserver.

Multiple workers

Flask-MQTT is currently not suitable for the use with multiple worker instances. So if you use a WSGI server like gevent or gunicorn make sure you only have one worker instance.


Make sure to disable Flasks autoreloader. If activated it spawns two instances of a Flask application. This leads to the same problems as multiple workers. To prevent Flask-MQTT from running code twice it is necessary to deactivate the automatic reloader.


Simply install the package as usual via pip:

$ pip install flask-mqtt

Or with conda from the conda-forge channel:

$ conda config --add channels conda-forge
$ conda install flask-mqtt


Basic Setup

from flask import Flask
from flask_mqtt import Mqtt

app = Flask(name) app.config['MQTT_BROKER_URL'] = 'mybroker.com' app.config['MQTT_BROKER_PORT'] = 1883 app.config['MQTT_USERNAME'] = 'user' app.config['MQTT_PASSWORD'] = 'secret' app.config['MQTT_REFRESH_TIME'] = 1.0 # refresh time in seconds mqtt = Mqtt(app)

@app.route('/') def index(): return render_template('index.html')

Subscribe to a topic

To subscribe to a topic simply use

. To make sure the subscription gets handled correctly on startup place the subscription inside an
callback function.
def handle_connect(client, userdata, flags, rc):

To handle the subscribed messages you can define a handling function by decorating it with

def handle_mqtt_message(client, userdata, message):
    data = dict(

To unsubscribe do:


Or if you want to unsubscribe all topics use



To publish a message you can use the

mqtt.publish('home/mytopic', 'this is my message')

Small publish/subscribe MQTT client


A small Test application to show how to use Flask-MQTT.


import eventlet import json from flask import Flask, render_template from flask_mqtt import Mqtt from flask_socketio import SocketIO from flask_bootstrap import Bootstrap


app = Flask(name) app.config['SECRET'] = 'my secret key' app.config['TEMPLATES_AUTO_RELOAD'] = True app.config['MQTT_BROKER_URL'] = 'broker.hivemq.com' app.config['MQTT_BROKER_PORT'] = 1883 app.config['MQTT_USERNAME'] = '' app.config['MQTT_PASSWORD'] = '' app.config['MQTT_KEEPALIVE'] = 5 app.config['MQTT_TLS_ENABLED'] = False app.config['MQTT_CLEAN_SESSION'] = True

Parameters for SSL enabled

app.config['MQTT_BROKER_PORT'] = 8883

app.config['MQTT_TLS_ENABLED'] = True

app.config['MQTT_TLS_INSECURE'] = True

app.config['MQTT_TLS_CA_CERTS'] = 'ca.crt'

mqtt = Mqtt(app) socketio = SocketIO(app) bootstrap = Bootstrap(app)

@app.route('/') def index(): return render_template('index.html')

@socketio.on('publish') def handle_publish(json_str): data = json.loads(json_str) mqtt.publish(data['topic'], data['message'])

@socketio.on('subscribe') def handle_subscribe(json_str): data = json.loads(json_str) mqtt.subscribe(data['topic'])

@socketio.on('unsubscribe_all') def handle_unsubscribe_all(): mqtt.unsubscribe_all()

@mqtt.on_message() def handle_mqtt_message(client, userdata, message): data = dict( topic=message.topic, payload=message.payload.decode() ) socketio.emit('mqtt_message', data=data)

@mqtt.on_log() def handle_logging(client, userdata, level, buf): print(level, buf)

if name == 'main': # important: Do not use reloader because this will create two Flask instances. # Flask-MQTT only supports running with one instance socketio.run(app, host='', port=5000, use_reloader=False, debug=False)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.