Using The Mosquitto_pub and Mosquitto_sub MQTT Client Tools- Examples

The Mosquitto_pub and Mosquitto_sub client utilities comes with the Mosquitto package, and are excellent tools for conducting quick tests and troubleshooting..

In this tutorial we are going to be looking at some examples of using these tools for publishing and subscribing.

Publishing Using The Mosquitto_pub Client

The screen shot shot below shows a simple publish, and a publish with the debug flag (-d) set.


In the first example the message is published and the client exits without displaying any messages.

If you enable the debugging using the -d flag then you can see the connect,publish and disconnect messages.

Notice the -h flag sets the host name or IP address. To get help use the –help flag.

e.g. mosquitto_pub –help

Useful Flag Options and Examples

-r  Sets retain flag
-n  Sends Null message useful for clearing retain message.
-p – Set Port number Default is 1883
-u – Provide a username
-P – Provide a password
-i – Provide client name
-I – Provide a client id prefix- Used when testing client restrictions using prefix security.

Publish With Username and Password

Uses -u username and -P password flags


Publish with Retain Flag

Uses -r Flag


Clear Retained Message

Uses the -r -n flag combination


Publish with Client Name

This  option is useful when testing client restrictions using prefixes or client names with ACLs.

Uses -i option. You could also use the -I option if you just needed prefixes.


Publishing JSON Data

JSON Data has a special format described here. When is comes to publishing with the mosquitto_pub client you need to escape the quotes so that they are included.

So don’t use {“status”:”off”} but instead use: {\”status\”:\”off\”}.

If you are sending multiple values then you need to put the entire string in quotes:

mosquitto_pub -h localhost -t test -m "{\"value1\":20,\"value2\":40}"

On Linux you can also use shell variables. If you have a shell variable called var1 then:

mosquitto_pub -h localhost -t test -m "{\"value1\":20,\"value2\":$var1}"

Mosquitto_pub -Publish Using SSL

Note: you will need to copy the CA.crt file into the appropriate directory. Use the –insecure switch if the name on the certificate doesn’t match the actual broker name.


There is also a option to publish a will message using the –will-topic flag but I couldn’t get this to work.

Using The Mosquitto_sub Client

This is useful for quickly monitoring a topic. Flag options are mostly the same as the mosquitto_pub client.

When you start this client it runs indefinitely until stopped using CTRL+C.


A useful option is the -C flag which will disconnect after receiving a certain number of messages.


Using the -v  (verbose option will show the topic name as well as the message.


The debug option -d flag is useful when you want to see the messages flags like qos and retain flag.


You can change the QOS when subscribing using the -q switch.



  • I didn’t get the scripts to work on Windows XP -Error not a valid win32 application
  • On Windows 7 and 10 they gave an error regarding a missing msvcr100.dll file. I found the file on my system and copied it to the Mosquitto directory and they worked OK.
  • You can download my windows install package that contains all the files for running the mosquitto broker and these clients from here.


Here is the pub manual page, and here is the sub manual page.

Video- Using the mosquitto_pub and mosquitto_sub client tools


The mosquitto_pub and mosquitto_sub client utilities are excellent tools for testing and troubleshooting MQTT and broker problems.

Other Related Articles and Resources:

Please rate? And use Comments to let me know more
[Total: 13    Average: 4.5/5]


    1. Yes but you will need to write the app to do it.
      The receiver must receive the command and then do a system call to execute the command.

  1. Excellent! Very much helpful.

    But I want to send and receive UTF-8 encoded string “∮ E⋅da = Q, n → ∞, ∑ f(i) = ∏ g(i), ∀x∈ℝ: ⌈x⌉ = −⌊−x⌋, α ∧ ¬β = ¬(¬α ∨ β)” using mosquitto_pub and mosquitto_sub applications. Is it possible? If so, Please share the details.

    1. Reading the docs then they support unicode but when I tried it the subscriber only displayed ascii.
      The tools are only really meant for testing and as such I only use them with simple strings.
      If you really do need this then make sure you use the latest versions as they have changed to support some of the features of MQTT version 5. I will do some tests and update the tutorial accordingly.
      This github question/response may be useful.

  2. Great info!
    I have Eclipse Mosquitto installed in a docker container on a Raspberry PI.
    It is working and showing MQTT data. I can use MQTT.fs from a windows 10 system and publish and subscribe.
    But, do not have access to any client tools.
    mosquitto_pub returns command not found. I want to use a python program to send cpu related data via MQTT but need this command. I have tried RPI-mosquitto and eclipse-mosquitto installed in containers with the same results. What am I doing wrong? Thanks

    1. On older windows installs the tools didn’t work and I forget why. They are included with he newer installs and work ok. You could download my install files for windows put them in a folder on the docker image called mos and then change to that directory and run them. There is no need to do any install.
      you can find the files by following this link.
      Let me know if it works ok

  3. HI Steve,
    Thanks for the Great tutorial. i am able to send the messages to the topics.
    Do you have any example use case programs to send data.

  4. Hello steve
    great tutorial
    I am getting this error
    can you tell me what i can do
    error: No connection could be made because the target machine actively refused it.

  5. Hello Steve, thanks for this nice documentation. I ham having some problem with using mosquitto_pub with SSLCertificate. On the client side, when i use:
    mosquitto_pub -h -t test -m “message” -d –cafile certs\ca.crt -p 8883 –insecure
    it shows the following error:
    Client mosqpub|13588-nb2166 sending CONNECT
    Error: A TLS error occurred.
    On the Broker side, it shows the following error:
    1534923031: New connection from on port 8883.
    1534923031: Socket error on client , disconnecting.
    I have already tested the Broker with MQTTfx and there it works fine with certificate. Could you help me out please ?

      1. Yes that is true. it is the same path also added in mosquitto conf in the line cafile.
        and it also shows the following error on the broker side.
        1534933587: New connection from on port 8883.
        1534933587: OpenSSL Error: error:14094418:SSL routines:ssl3_read_bytes:tlsv1 alert unknown ca
        1534933587: OpenSSL Error: error:140940E5:SSL routines:ssl3_read_bytes:ssl handshake failure
        1534933587: Socket error on client , disconnecting.

        Is it a problem to use a selfed signed certificate? How to solve this problem?

      2. Hello Steve, I found the issue. It was showing the error that the CA is unknown as i had put the same information in both the information in server and ca crt files. For other users, please do not forget to read the yellow note on this webpage or else you will end up like me. 😉
        In short if you get this error from OpenSSL, it means the certificates are not correct:
        1534938680: New connection from on port 8883.
        1534938680: OpenSSL Error: error:14094418:SSL routines:ssl3_read_bytes:tlsv1 alert unknown ca
        1534938680: OpenSSL Error: error:140940E5:SSL routines:ssl3_read_bytes:ssl handshake failure
        1534938680: Socket error on client , disconnecting.
        Now it mosquitto_pub as well as libmosquitto are working correctly. THank you again.

  6. mosquitto_pub -h -p 1883 -t test -m “Electroll”

    when using this command or any other commands with publish and subscribe the ting crashes ,
    receiving messages like “mosquitto_pub.exe stopped working” what should i do
    i also checked netstat -a , port 1883 is present

Leave a Reply

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