Install & Compatibility
Where this runs
tested against v1.6.0.20240321 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.130s · 18.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.118s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import paho.mqtt.client as mqtt
client: mqtt.Client
✗ from types_paho_mqtt import Client
`types-paho-mqtt` provides stubs, not runtime code. You import from the actual `paho-mqtt` library.
MQTTMessage
✓ import paho.mqtt.client as mqtt
def on_message(client: mqtt.Client, userdata: object, msg: mqtt.MQTTMessage): ...
`MQTTMessage` is a type used in callbacks for `paho-mqtt`.
This example demonstrates basic `paho-mqtt` client usage with type hints, showing how `types-paho-mqtt` is used by a type checker. It connects to a public test broker, subscribes to a topic, publishes a message, and then disconnects. Note the type annotations for `client`, `userdata`, `flags`, `rc`, and `msg`.
import paho.mqtt.client as mqtt
import time
import os
# Callbacks for paho-mqtt < 2.0.0 or CallbackAPIVersion.VERSION1
def on_connect(client: mqtt.Client, userdata: object, flags: dict, rc: int) -> None:
if rc == 0:
print(f"Connected to MQTT Broker! Result code: {rc}")
client.subscribe("test/topic")
else:
print(f"Failed to connect, return code {rc}\n")
def on_message(client: mqtt.Client, userdata: object, msg: mqtt.MQTTMessage) -> None:
print(f"Received `{msg.payload.decode()}` from `{msg.topic.decode()}`")
# Initialize the MQTT Client (assumes paho-mqtt < 2.0.0 for this stub version)
client: mqtt.Client = mqtt.Client() # Default to paho-mqtt 1.x behavior
client.on_connect = on_connect
client.on_message = on_message
# Connect to a public test broker. For production, use a secure connection to your own broker.
try:
print("Attempting to connect to test.mosquitto.org:1883")
client.connect("test.mosquitto.org", 1883, 60)
client.loop_start() # Start a non-blocking loop
# Publish a message
print("Publishing a test message...")
client.publish("test/topic", "Hello from types-paho-mqtt example!", qos=1)
time.sleep(5) # Give some time for messages to be processed
client.loop_stop()
client.disconnect()
print("Disconnected from broker.")
except Exception as e:
print(f"An error occurred during MQTT operations: {e}")
Debug
Known issues
gotchaInstalling `types-paho-mqtt` only provides type hints; it does not install the `paho-mqtt` library itself. You must install both packages for your code to run.fixEnsure both `paho-mqtt` and `types-paho-mqtt` are installed: `pip install paho-mqtt types-paho-mqtt`
affects: All versions
breakingThe current `types-paho-mqtt` version `1.6.0.20240321` is designed for `paho-mqtt` version 1.x. It is NOT fully compatible with `paho-mqtt` version 2.0.0 and later, which introduced significant breaking changes to callback signatures (`on_message`, `on_connect`, etc.) and `MQTTMessage` attributes (e.g., `topic` is now `str` instead of `bytes`).fixIf using `paho-mqtt` 2.x, you may encounter type errors. Monitor the `typeshed` repository or PyPI for an updated `types-paho-mqtt` package specifically for `paho-mqtt` 2.x. Alternatively, if your project relies on precise type checking, consider pinning `paho-mqtt` to a 1.x version (e.g., `paho-mqtt<2.0.0`).
affects: types-paho-mqtt <= 1.6.0.20240321 when used with paho-mqtt >= 2.0.0
gotchaType checkers (like MyPy) need to be configured correctly to discover and use installed stub files. Ensure your `mypy.ini` (or equivalent) does not exclude your project's virtual environment or site-packages from analysis.fixVerify MyPy configuration. A basic `pyproject.toml` or `mypy.ini` should suffice for most projects. For example, `mypy --install-types --non-interactive` can help MyPy find and install missing stubs.
affects: All versions
gotchaThere might be slight discrepancies or incompleteness in typing stubs for edge cases or very recent `paho-mqtt` features, especially if the `paho-mqtt` library updates rapidly and the typeshed stubs haven't caught up.fixIf you encounter incorrect type hints, consider contributing to `typeshed` to improve the `paho-mqtt` stubs or create a custom stub file for your project to override specific definitions.
affects: All versions
Upgrade
Version history
1.6.0.20240321latest on PyPI · released Mar 21, 2024
Audit
Dependencies
paho-mqttrequiredThese are typing stubs for the `paho-mqtt` library. The `paho-mqtt` library itself must be installed for runtime functionality.