The Eclipse Paho MQTT Python Client library provides classes for applications to connect to an MQTT broker, publish messages, and subscribe to topics to receive messages. It supports MQTT versions 5.0, 3.1.1, and 3.1, and is designed for lightweight publish/subscribe messaging, suitable for IoT and M2M communication where bandwidth or code footprint is a concern. The current stable version is 2.1.0, with regular updates and an active development cadence as part of the Eclipse Foundation projects.
pip install paho-mqttVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to connect to an MQTT broker, subscribe to a topic, and publish messages using the `paho-mqtt` client. It configures `on_connect` and `on_message` callbacks and uses `loop_start()` to handle network traffic in a background thread. It explicitly uses `CallbackAPIVersion.VERSION2` for modern MQTTv5 features and future compatibility. Environment variables are used for broker host/port for easy configuration.
Initialize the client with `mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, client_id)`. If you need to retain older callback signatures, explicitly use `mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION1, client_id)` but plan for migration to `VERSION2` as `VERSION1` is deprecated and will be removed in v3.0.
Upgrade your Python environment to version 3.7 or newer.
Update calls to `connect_srv()` to include the `bind_port` argument.
Always use `==` for comparison with return codes (e.g., `if rc == 0:`).
Always include `client.subscribe()` calls within your `on_connect` callback function. This ensures that subscriptions are automatically renewed upon successful reconnection to the broker.
Migrate your callback functions to use the `CallbackAPIVersion.VERSION2` signature and explicitly pass `mqtt_client.CallbackAPIVersion.VERSION2` to the `Client` constructor to prepare for future library updates.
Ensure `paho-mqtt` is installed in the correct environment by running `pip install paho-mqtt` (or `pip3 install paho-mqtt` for Python 3). Also, check that no script in the current directory or Python path is named `paho.py` or `paho/mqtt.py` that could cause a naming conflict.
Verify that an MQTT broker (e.g., Mosquitto) is running on the specified host and port, and that network connectivity and firewall rules allow the connection. Also, ensure the correct host and port are being used in the client's `connect()` method.
Correct the instantiation to `client = mqtt.Client()` with a capital 'C'. Also, check that your Python script filename is not `paho.py`, `client.py`, or any other name that conflicts with the library's module structure.
Ensure the client's network loop (e.g., `client.loop_start()` or `client.loop_forever()`) is running to handle reconnections automatically. Implement robust error handling around publish calls and potentially use `on_disconnect` callbacks to detect disconnections and manage reconnection logic.
Ensure the client has successfully connected to the broker before attempting to publish or subscribe. Use `client.loop_start()` or `client.loop_forever()` to manage the network connection in a background thread, which also handles automatic reconnections. Check the return code of `client.connect()` and handle connection failures in the `on_connect` callback.