{"id":8742,"library":"types-paho-mqtt","title":"Typing stubs for paho-mqtt","description":"This library provides PEP 561 compliant typing stubs for the `paho-mqtt` client library, enabling static type checking tools like MyPy to verify correct usage of `paho-mqtt` APIs. It is part of the `typeshed` project, which centrally maintains type hints for many popular Python packages. The current version, `1.6.0.20240321`, corresponds to `paho-mqtt` version 1.6.0. As a typeshed package, it updates periodically as the upstream library changes or as typeshed contributors enhance the stubs.","status":"active","version":"1.6.0.20240321","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","type-hints","mqtt","stubs","paho-mqtt","typeshed"],"install":[{"cmd":"pip install paho-mqtt types-paho-mqtt","lang":"bash","label":"Install paho-mqtt and its stubs"}],"dependencies":[{"reason":"These are typing stubs for the `paho-mqtt` library. The `paho-mqtt` library itself must be installed for runtime functionality.","package":"paho-mqtt","optional":false}],"imports":[{"note":"`types-paho-mqtt` provides stubs, not runtime code. You import from the actual `paho-mqtt` library.","wrong":"from types_paho_mqtt import Client","symbol":"Client","correct":"import paho.mqtt.client as mqtt\nclient: mqtt.Client"},{"note":"`MQTTMessage` is a type used in callbacks for `paho-mqtt`.","symbol":"MQTTMessage","correct":"import paho.mqtt.client as mqtt\ndef on_message(client: mqtt.Client, userdata: object, msg: mqtt.MQTTMessage): ..."}],"quickstart":{"code":"import paho.mqtt.client as mqtt\nimport time\nimport os\n\n# Callbacks for paho-mqtt < 2.0.0 or CallbackAPIVersion.VERSION1\ndef on_connect(client: mqtt.Client, userdata: object, flags: dict, rc: int) -> None:\n    if rc == 0:\n        print(f\"Connected to MQTT Broker! Result code: {rc}\")\n        client.subscribe(\"test/topic\")\n    else:\n        print(f\"Failed to connect, return code {rc}\\n\")\n\ndef on_message(client: mqtt.Client, userdata: object, msg: mqtt.MQTTMessage) -> None:\n    print(f\"Received `{msg.payload.decode()}` from `{msg.topic.decode()}`\")\n\n# Initialize the MQTT Client (assumes paho-mqtt < 2.0.0 for this stub version)\nclient: mqtt.Client = mqtt.Client() # Default to paho-mqtt 1.x behavior\nclient.on_connect = on_connect\nclient.on_message = on_message\n\n# Connect to a public test broker. For production, use a secure connection to your own broker.\ntry:\n    print(\"Attempting to connect to test.mosquitto.org:1883\")\n    client.connect(\"test.mosquitto.org\", 1883, 60)\n    client.loop_start() # Start a non-blocking loop\n\n    # Publish a message\n    print(\"Publishing a test message...\")\n    client.publish(\"test/topic\", \"Hello from types-paho-mqtt example!\", qos=1)\n    time.sleep(5) # Give some time for messages to be processed\n\n    client.loop_stop()\n    client.disconnect()\n    print(\"Disconnected from broker.\")\n\nexcept Exception as e:\n    print(f\"An error occurred during MQTT operations: {e}\")\n","lang":"python","description":"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`."},"warnings":[{"fix":"Ensure both `paho-mqtt` and `types-paho-mqtt` are installed: `pip install paho-mqtt types-paho-mqtt`","message":"Installing `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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`).","message":"The 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`).","severity":"breaking","affected_versions":"types-paho-mqtt <= 1.6.0.20240321 when used with paho-mqtt >= 2.0.0"},{"fix":"Verify 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.","message":"Type 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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.","message":"There 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the actual `paho-mqtt` library: `pip install paho-mqtt`","cause":"`paho-mqtt` library is not installed, only its type stubs (`types-paho-mqtt`) are present.","error":"ModuleNotFoundError: No module named 'paho.mqtt.client'"},{"fix":"This specific error likely means your `paho-mqtt` is too old for the `CallbackAPIVersion.VERSION2` enum member. Update `paho-mqtt` to 2.0.0 or later, or remove the `callback_api_version` argument if you intend to use 1.x behavior (which is the default in 2.x if not specified).","cause":"You are using `paho-mqtt` version < 2.0.0 (which doesn't have `CallbackAPIVersion.VERSION2` as a valid argument) but your type checker is using stubs that might imply it, or you are explicitly passing an incompatible value.","error":"error: Argument \"callback_api_version\" to \"Client\" has incompatible type \"Literal[2]\"; expected \"CallableAPIVersion\""},{"fix":"Adjust your callback function signatures to match the `paho-mqtt` version you are using AND the `CallbackAPIVersion` you've specified (if any). For `paho-mqtt < 2.0.0` or `CallbackAPIVersion.VERSION1`, `userdata` is `object`. For `paho-mqtt >= 2.0.0` with `CallbackAPIVersion.VERSION2`, `userdata` is `dict`.","cause":"This is a common type error when migrating `paho-mqtt` 1.x code to 2.x (or vice-versa with incorrect stubs). The `userdata` parameter in callbacks changed type from `object` to `dict` (for `VERSION2`) and back again, or the order/types of other arguments changed.","error":"error: Incompatible types in assignment (expression has type \"Callable[[Client, object, dict, int], None]\", variable has type \"Callable[[Client, dict, dict, int], None]\")"},{"fix":"If using `paho-mqtt >= 2.0.0`, you can usually remove `.decode()` from `msg.topic`. For `msg.payload`, it remains `bytes` and needs `.decode()`. If the type checker still complains, it means your stubs are out of date for your `paho-mqtt` version.","cause":"In `paho-mqtt` versions before 2.0.0, `msg.topic` and `msg.payload` were `bytes`. In 2.0.0+, `msg.topic` is `str`. If you are using `paho-mqtt >= 2.0.0` and `types-paho-mqtt` stubs for 1.x, the stubs might incorrectly report `topic` as `bytes`.","error":"error: 'MQTTMessage' has no attribute 'topic' (note: perhaps 'topic.decode()'?)"}]}