Paho Python MQTT Client Changes for MQTTv5 Support

The Paho Python client version 1.5.1 included support for MQTTv5. Because of the new capabilities of MQTTv5 there have been changes to many of the common functions like connect,subscribe and publish etc.

The aim of this tutorial is to point out the main changes, and what you need to do in your code to use the new features.

MQTT Protocol Version

If you want to use the new MQTTv5 capabilities then is important to specify the protocol version you want to use. Supported versions are:

  • MQTTv31 = 3
  • MQTTv311 = 4
  • MQTTv5 = 5

Therefore when creating the client for MQTTv5 use:

client = mqtt.Client("mqtt5_client",protocol=MQTTv5)

Connection Function

MQTT v3.1.1

connect(host, port=1883, keepalive=60, bind_address="")


connect(self, host, port=1883, keepalive=60, bind_address="", bind_port=0,
clean_start=MQTT_CLEAN_START_FIRST_ONLY, properties=None)

The most important addition is the properties object.

The properties object is present in other function calls, and so it is important to understand how to use it and we cover this next.

Properties Object

The properties object varies according to what function you will use it in.

To use it in the connection function you first need to import the properties class and then create a properties object using the following syntax:


The following are the available packet types (taken from the code:


In addition you will need to set property attributes. In the example code below we set the maximum packet size the client can receive.

Because this is done in the connection message we use the Connect packet type:


Once we have the properites object we set the attributes as shown in the code below:

from import Properties
from paho.mqtt.packettypes import PacketTypes 

To make your code work with both MQTTv5 and MQTTv3.1.1 you need to set the properties object to None when using MQTTv3.1.1

So Instead of


you would use


Note:  MQTTv5 Properties by Message Type has list of property fields that are available in the connection message and other message types.

Connect Acknowledge Callback Function

The server can return lots of information in the properties field of the CONNACK message and so the callback function must include it. Below shows CONNACK callbacks for v3.1.1 and v5 as defined in the latest client code..

Old signature for MQTT v3.1 and v3.1.1 is:
on_connect(client, userdata, flags, rc)

signature for MQTT v5.0 client:
on_connect(client, userdata, flags, reasonCode, properties=None)

Notice the extra properties field.

However existing code written for v3.1.1 used the following callback signature:

connect(client, userdata, flags, rc)

This will still work with MQTTv3.1.1 but you will get an error with MQTTv5

To make the callback work with v3.1.1 and v5 connections use:

on_connect(client, userdata, flags, rc, properties=None)

The following functions have also changed and you need to use the same logic as described above.

Subscribe and Subscribe Callback

MQTT v3.1.1 and v3.1

subscribe(topic, qos=0)

and for MQTT v5.0:

subscribe(self, topic, qos=0, options=None, properties=None)

Subscribe Callback

Old signature for MQTT v3.1.1 and v3.1 is:
on_ subscribe(client, userdata, mid, granted_qos)

and for the MQTT v5.0 client:
on_subscribe(client, userdata, mid, granted_qos, properties=None)

UnSubscribe Callback

Old signature for MQTT v3.1.1 and v3.1 is:
unsubscribe_callback(client, userdata, mid)

and for the MQTT v5.0 client:
unsubscribe_callback(client, userdata, mid)

Publish Message

Old signature for MQTT v3.1.1 and v3.1 is:
publish(self, topic, payload=None, qos=0, retain=False)
and for the MQTT v5.0 client:
publish(self, topic, payload=None, qos=0, retain=False, properties=None)


Changes in the MQTTv5 protocol mean that you will need to make script changes if you want your old code to work with both protocols.

Resources and Related Tutorials


Please rate? And use Comments to let me know more


  1. typo in subscribe_callback() for the MQTT v5.0 client:
    on_subscribe(client, userdata, mid, granted_qos, properties=None)

    should be:
    on_subscribe(client, userdata, mid, reasonCodes, properties)

    1. tks for that I just checked the code and it looks like
      on_subscribe(client, userdata, mid, granted_qos,reasonCodes properties=None)
      I will need to check further

Leave a Reply

Your email address will not be published.