Examining MQTTv5 User Properties


User properties allow you to add your own meta data to MQTT messages.

User properties consist of an array of user defined UTF-8 key/value pairs and are carried in the message property field.

 This means if you want to include numbers they need to be converted to strings.

If you are familiar with http it looks very similar to how http headers work.

User Properties effectively allow the user to extend the MQTT protocol, and can be present in all messages and responses.

Because user properties are user defined they only have meaning to that user implementation.

User properties can be sent between client and server and client to client depending on the message type used to send them.

User properties can be sent in various message types. User Properties set in the connection message for example aren’t passed on to the receiving client, whereas user properties set in the publish message are sent to the receiving client.

Connection User Properties

Connection message user defined properties are sent from client to server, and they are not transmitted on to the receiving client.

They are used to send connection related information to the server.

The server must be able to use these properties, and so these properties would be defined by the server, and so are server dependent.

Publish User Properties

These are probably the most useful as they are transmitted to the receiving client.

They will be most probably be used for sending meta data between clients. e.g

  • Message numbering
  • Timestamp
  • Routing information

To illustrate I have a simple publish and subscribe script that use a client to publish and another client to receive the message.

User properties are set as an array of key/value pairs as you can clearly see in the code below.

The publisher sets user properties using the code below

print("sending message user properties set")
client_pub.publish("test/mqtt","test message",\
user_property=[('sfilename', 'test.txt'),('dfilename', 'test.txt')])

It could be used for example for file transfer where the file names are sent in the user properties and the file contents in the payload.

This means that the file can be kept as binary as the file meta data is in the user properties and not in the payload as would be the case in MQTT v3.1

The screen shot below shows what is received.


This tutorial show you  how to Send a File Using MQTTv3.1.1 and Python without user properties.

User Properties Python Code

Here is the code that creates the user properties

print("sending message user properties set")
client_pub.publish("test/mqtt","test message",properties=properties)

Decoding Received User Properties

Below is the on_message callback were we extract the user properties from the incoming message.

You should notice that the user properties are part of the message properties.

def on_message(client, userdata, message):

    print('RECV Topic = ',message.topic)
    print('RECV MSG =', msg)
    print("properties received= ",message.properties)
    print("user properties received= ",user_properties)

Here is a screen shot of the output.


In this case the only property was the user property


The addition of properties field was probably the most significant change in the MQTT protocol, and allowed much more control information to be exchanged, and importantly user defined control information using user properties.

Download Scripts Used in MQTTV5 Tutorials



Related Tutorials:

Please rate? And use Comments to let me know more


  1. Hi Steve,
    Can u please help me ,how to use mosquitto_pub to publish the properties .
    for example:
    mosquitto_pub -t ‘test’ -m ‘hello’ –property publish response-topic ‘ack1’
    even though i am unable to see those properties in publish log

    1. Try
      mosquitto_pub -t test -m ‘hello’ –property publish response-topic ack1 -h -V 5

      I was unable to view the property in the mosquitto_sub client to check but I will try to set up a Python script to check it
      and let you know if it needs changing

        1. Hi steve,
          Yes in python script it works. But the issue is mosquitto_sub can only receive payload message but not properties wright.

  2. What are the contents of user-property.py? More specifically, how does the subscriber display the user-property?

    1. The user properities are shown in the last diagram as an array of key value pairs. I will expand the tutorial to show the python code to display them and create them.

  3. Great documentation, thank you very much.
    I’d like to add the following creation code concering the user property to work:
    publish_properties = mqtt.Properties(PacketTypes.PUBLISH)
    publish_properties.UserProperty = (“MessageType”, “DeviceCreationRequest”)
    self.mqttClient.publish(topic,payload=payload, qos=0, retain=False, properties=publish_properties)

    Hope it might help others

Leave a Reply

Your email address will not be published. Required fields are marked *