Changelog

v2.1.0 - 2024-04-29

  • Make transition from 1.x to 2.x version smoother (Closes #831)

  • Fix “protocol” property (Closes #820)

  • Fix publish() a bytearray payload (Closes #833)

  • Fix some type annotations (Closes #828)

  • Fix loop_stop() not stopping thread when called from callback (Closes #809)

  • Fix some documentation errors (Closes #817, #823, #832, #838)

  • Add support for Unix socket (Closes #829)

  • Fix flaky test (Closes #789)

v2.0.0 - 2024-02-10

This release include breaking change. See migrations for more details on how to upgrade.

  • BREAKING Added callback_api_version. This break ALL users of paho-mqtt Client class. See docs/migrations.rst or online version for details on how to upgrade. tl; dr; add CallbackAPIVersion.VERSION1 to first argument of Client()

  • BREAKING Drop support for Python 2.7, Python 3.5 and Python 3.6 Minimum tested version is Python 3.7 Python version up to Python 3.12 are tested.

  • BREAKING connect_srv changed it signature to take an additional bind_port parameter. This is a breaking change, but in previous version connect_srv was broken anyway. Closes #493.

  • BREAKING Remove some deprecated argument and method:

    • max_packets argument in loop(), loop_write() and loop_forever() is removed

    • force argument in loop_stop() is removed

    • method message_retry_set() is removed

  • BREAKING Remove the base62, WebsocketWrapper and ConnectionState, as user shouldn’t directly use them.

  • Possible breaking change: Add properties to access most Client attribute. Closes #764. Since this add new properties like logger, if a sub-class defined logger, the two logger will conflict.

  • Add version 2 of user-callback which allow to access MQTTv5 reason code & properties that were missing from on_publish callback. Also it’s more consistent in parameter order or between MQTTv3 and MQTTv5.

  • Add types to Client class, which caused few change which should be compatible. Known risk of breaking changes:

    • Use enum for returned error code (like MQTT_ERR_SUCCESS). It use an IntEnum which should be a drop-in replacement. Excepted if someone is doing “rc is 0” instead of “rc == 0”.

    • reason in on_connect callback when using MQTTv5 is now always a ReasonCode object. It used to possibly be an integer with the value 132.

    • MQTTMessage field “dup” and “retain” used to be integer with value 0 and 1. They are now boolean.

  • Add support for ALPN protocols on TLS connection. Closes #790 & #648.

  • Add on_pre_connect() callback, which is called immediately before a connection attempt is made.

  • Fix subscribe.simple with MQTTv5. Closes #707.

  • Use better name for thread started by loop_start. Closes #617.

  • Fix possible bug during disconnection where self._sock is unexpectedly None. Closes #686 & #505.

  • Fix loading too weak TLS CA file but setting allowed ciphers before loading CA. Closes #676.

  • Allow to manually ack QoS > 0 messages. Closes #753 & #348.

  • Improve tests & linters. Modernize build (drop setup.py, use pyproject.toml)

  • Fix is_connected property to correctly return False when connection is lost and loop_start/loop_forever isn’t used. Closes #525.

  • Fix wait_for_publish that could hang with QoS == 0 message on reconnection or publish during connection. Closes #549.

  • Correctly mark connection as broken on SSL error and don’t crash loop_forever. Closes #750.

  • Fix handling of MQTT v5.0 PUBREL messages with remaining length not equal to 2. Closes #696.

  • Raise error on subscribe() when topic is an empty list. Closes #690.

  • Raise error on publish.multiple() when msgs is an empty list. Closes #684.

  • Don’t add port to Host: header for websockets connections when the port if the default port. Closes #666.

v1.6.1 - 2021-10-21

  • Fix Python 2.7 compatibility.

v1.6.0 - 2021-10-20

  • Changed default TLS version to 1.2 instead of 1.0.

  • MQTT connection attempts now use a timeout of 5 seconds rather than the configured keepalive interval

  • Fix incoming MQTT v5 messages with overall property length > 127 bytes being incorrectly decoded. Closes #541.

  • MQTTMessageInfo.wait_for_publish() and MQTTMessageInfo.is_published() will now raise exceptions if called when the publish call produced an error. Closes #550.

  • Remove periodic retry checks for outgoing messages with QoS>0. This means that outgoing messages will only be retried on the client reconnecting to the server. They will not be retried when the client is still connected.

  • The rc parameter in the on_disconnect callback now has meaningful values in the case of an error. Closes #441.

  • Callbacks can now be applied to client instances using decorators.

  • PUBACK messages are now sent to the broker only after the on_message callback has returned.

  • Raise exceptions when attempting to set MQTT v5 properties to forbidden values. Closes #586.

  • Callbacks can now be updated from within a callback.

  • Remove _out_packet_mutex and _current_out_packet_mutex and convert the _out_packet queue use to thread safe.

  • Add basic MQTT v5 support to the subscribe and publish helper functions. Closes #575.

  • Fix on_disconnect() sometimes calling the MQTT v3.x callback when it should call the MQTT v5 callback. Closes #570.

  • Big performance improvement when receiving large payloads, particularly for SSL. Closes #571,

  • Fix connecting with MQTT v5 to a broker that doesn’t support MQTT v5. Closes #566.

  • Removed ancient Mosquitto compatibility class.

  • Fix exception on calling Client(client_id=””, clean_session=False). Closes #520.

  • Experimental support for Websockets continuation frames. Closes #500. Closes #89.

  • Properties.json() now converts Correlation Data bytes() objects to hex. Closes #555.

  • Only use the internal sockpair wakeup when running with loop_start() or loop(). This removes problems when running with an external event loop.

  • Drain all of sockpairR bytes to avoid unnecessary wakeups and possible timeouts. Closes #563.

  • Add timeout to MQTTMessageInfo:wait_for_publish().

v1.5.1 - 2020-09-22

  • Exceptions that occur in callbacks are no longer suppressed by default. They can optionally be suppressed by setting client.suppress_exceptions = True. Closes #365.

  • Fix PUBREL remaining length of > 2 not being accepted for MQTT v5 message flows. Closes #481.

  • Fix MQTT v5 properties not being sent on retried or queued messages.

  • Fix errors related to detection of MQTT v5 first connections.

  • Fix for changes related to Python 3.9.

v1.5.0 - 2019-10-30

  • Add support for clean_session on subscribe helper. Closes #219

  • Add support for non-standard bridge connection. Closes #282

  • Fix hang with QoS 2 message and clean_session = False. The fix replace hang with message DROP. See README for known limitation. Closes #284 and #286

  • Fix connection establishement timeout. Closes #291 and #288

  • Add support for connecting through a proxy. Closes #315

  • Add MQTT v5 support. Closes #334

  • Improve error message when sending queue is full. Closes #378

  • Improve error handling during initialization on edge case. Closes #387 and #388

  • Allow to specify local client port used (similar to bind_address). Closes #390

  • Add method is_connected to know if MQTT connection is established. Closes #414

  • Set connection timeout to keepalive. Closes #425

v1.4.0 - 2018-09-02

  • Fix hang when client restarted and broker resumed a session with Qos2 message. Closes #284. Note: this change replace the hang by a message lost ! See README for current limitation of paho-mqtt.

  • Fix reconnection loop when a clean_session=True client reconnect while Qos2 message are being sent. Note: this change replace the infinite reconnection loop by a possible duplicate QoS2 message. Only clean_session=True client are affected, see README for current limitation of paho-mqtt.

  • Catch and log any exception raised by user callback. Closes #294.

  • Improve support for external event loop (like asyncio). Closes #235.

  • Fix order of message with publish.multiple helper. Closes #87.

  • Fix hang on wait_for_published() on bad network. Closes #309.

  • Fix an issue with Websocket that seems to happen only on Windows. Closes #268.

  • Fix issue with Websocket payload size between 127 and 65536. Closes #267.

  • Closes socket in client destructor to avoid FD leak. Closes #170.

  • Fix uncaught timeout exception during connection. Closes #288.

  • Remove dup flag on PUBREL packet. Closes #298.

  • Use secure entropy source for Websocket mask_key (urandom). Closes #305.

  • Fix mid generation that was not thread-safe.

  • Replace print() statements with proper logging. Closes #214.

  • Allow insecure TLS on publish and subscribe helpers. Closes #299.

  • Allow to remove authentication (reset username to None). Closes #259.

  • Add support for the non-standard bridge mode. Closes #282.

v1.3.1 - 2017-10-09

  • Fix reconnect_delay_set which ignored the max_delay. Closes #218.

  • Fix crash when connection is lost while trying to send message. Closes #208.

  • Fix issue with unicode topic when some character were multi-bytes UTF-8.

  • Fix issue with empty Client ID with broker that don’t support them. Closes #209.

  • Fix issue with tls_set that did not allowed cert_reqs=ssl.CERT_NONE. Closes #123.

  • Relax requirement on pytest-runner, it’s now only required for tests. Closes #207, #227.

v1.3.0 - 2017-06-20

  • BREAKING Requires Python 2.7 or 3.4+. Closes #163.

  • BREAKING Remove support for SSL without SSLContext (Requires Python 2.7.9+ or 3.2+). Closes #115.

  • BREAKING on_connect callback is now always called flags. Previously this callback could accepts 3 OR 4 arguments, now it must accepts 4. Closes #197.

  • BREAKING tls_insecure_set() must now be called after tls_set()

  • Allow username and password to be zero length (as opposed to not being present). Closes #80.

  • Allow zero length client ids when using MQTT v3.1.1.

  • Add SSLContext support, including SNI. Closes #11.

  • Improved support for unicode topic and binary payload. Closes #15, #16.

  • Allow arbitrary Websocket headers and path. Closes #169.

  • Fix issue with large inbound payload over Websocket. Closes #107.

  • Add exponential delay for reconnection. Closes #195.

  • Move unit tests to pytest (#164) and tox (#187)

  • Add support for standard Python logging. Closes #95.

  • Fix duplicate incoming QoS==2 message. Closes #194.

v1.2.3 - 2017-04-20

  • Fix possible hang of TLS connection during handshake. Closes #3.

  • Fix issue with publish helper with TLS connection. Closes #180.

  • Fix installation issue on non-UTF-8 system. Closes #181.

  • Fix non-working Websocket over TLS connection. Closes #182.

v1.2.2 - 2017-04-11

  • Fix message lost when using paho.mqtt.publish helper with QoS=0 message. Closes #172.

v1.2.1 - 2017-04-03

  • Handle unicode username and passwords correctly. Closes #79.

  • Fix handling of invalid UTF-8 topics on incoming messages - the library now does not attempt to decode the topic - this will happen when the user accesses msg.topic in the on_message callback. If the topic is not valid UTF-8, an exception will be raised. Closes #75.

  • Fix issue with WebSocket connection in case of network issue (timeout or connection broken). Closes #105.

  • Fix issue with SSL connection, where latest incoming message may be delayed or never processed. Closes #131.

  • Fix possible message lost with publish.single and publish.multiple. Closes #119.

v1.2 - 2016-06-03

  • Client.publish() now returns an MQTTMessageInfo object. The MQTTMessageInfo object behaves like a tuple of (rc, mid) for backwards compatibility but also provides two functions: is_published() and wait_for_published(). This allows a client to determine whether any given message has been published without need for a callback, and also allows the client to block waiting until the message has been sent.

  • Further fix for Client constructor for the case where “localhost” is unresolvable.

  • Add paho.mqtt.subscribe module, with simple() and callback() helper functions.

  • Allow ^C to interrupt client loop.

  • Fix for keepalive=0 causing an infinite disconnect/reconnect loop. Closes #42.

  • Modify callbacks definition/structure to allow classical inheritance. Closes #53, #54.

  • Add websockets support.

  • Default MQTT version is again changed to v3.1.1.

  • Client.subscribe() now accepts unicode type topic inputs on Python 2. Closes #16.

  • paho.mqtt.publish() now raises an MQTTException on a CONNECT failure, rather than blindly continuing. Closes #6.

  • Don’t block on TLS sockets on Python 3. Closes #2.

  • Client.publish() now accepts bytes() payloads on Python 3. Closes #1.

  • Don’t attempt to join() own thread. Closes #14.

  • Allow the use of Client.message_callback_add() from inside callbacks. Closes #12.

  • Use a monotonic time source for keeping track of time, if available. Closes #56.

v1.1 - 2015-01-30

  • Add support for wildcard certificates. Closes #440547.

  • Default connection behaviour has been reverted to MQTT v3.1 instead of v3.1.1. There is as yet insufficient support for v3.1.1 to rely on, and current v3.1 implementations do not return the correct CONNACK code to allow detection of the fault. Closes #451735.

  • Fix incorrect handling of queued messages after reconnecting. Closes #452672.

  • Fix possible race condition if the connection in loop_start() does not complete before loop_stop() is called, meaning the network thread never ends. Closes #448428. Thanks to Kees Bakker.

v1.0.2 - 2014-09-13

  • Fix “protocol” not being used in publish.single()

  • Fix Client constructor for the case where “localhost” is unresolvable. Closes #439277.

  • Don’t attempt to encode topic to utf-8 twice. Thanks to Luc Milland.

  • Handle “unicode” type payloads on Python 2.7. Thanks to Luc Milland.

  • Fix reconnecting after sending more QoS>0 messages than inflight messages is set to, whilst connecting. Closes #443935. Thanks to Hiram van Paassen.

  • Fix possible race condition when connecting with TLS and publishing at the same time, which could lead to PUBLISH data being sent before any other messages and unencrypted. Closes #443964. Thanks to Hiram van Paassen.

  • Handle exceptions from select() in client loop() function. Closes #443881. Thanks to Jeff Jasper.

v1.0.1

  • Fix incorrect reconnect that occurred if calling loop_stop() before disconnect().

v1.0

  • Default protocol is now MQTT v3.1.1.

  • Client will reconnect using MQTT v3.1 if a v3.1.1 connection fails due to the incorrect protocol version number.

  • All strings are now correctly encoded as utf-8.

  • Add support for “session present” flag in on_connect callback.

v0.9.1

  • Fix CONNECT packet for MQTT v3.1.1.

  • Fix potential lockup when publishing from on_publish callback.

  • Add version information to paho.mqtt.__version__