{"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":"python","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,"search_vec":"'1.6.0':65 '1.6.0.20240321':58 '561':11 'api':37 'central':46 'chang':77 'check':25 'client':20 'compliant':12 'contributor':81 'correct':31 'correspond':59 'current':56 'enabl':22 'enhanc':82 'hint':49,88 'librari':8,21,76 'like':27 'maintain':47 'mani':51 'mqtt':6,19,36,63,89,93 'mypi':28 'packag':54,69 'paho':5,18,35,62,92 'paho-mqtt':4,17,34,61,91 'part':40 'pep':10 'period':72 'popular':52 'project':44 'provid':9 'python':53 'static':23 'stub':2,14,84,90 'tool':26 'type':1,13,24,48,85,87 'type-hint':86 'typesh':43,68,80,94 'updat':71 'upstream':75 'usag':32 'verifi':30 'version':57,64","created_at":"2026-04-16T17:03:45.622609+00:00","updated_at":"2026-04-16T17:03:45.622609+00:00","problems":{"verify_error":"error: Failed to parse: `paho-mqtt types-paho-mqtt`\n  Caused by: Expected one of `@`, `(`, `<`, `=`, `>`, `~`, `!`, `;`, found `t`\npaho-mqtt types-paho-mqtt\n          ^"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.6.0.20240321","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/paho-mqtt.md","pypi":"https://pypi.org/project/types-paho-mqtt/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","http-networking","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}