{"id":5840,"library":"aiomqtt","title":"aiomqtt","description":"aiomqtt is an idiomatic asyncio MQTT client for Python, providing a modern asynchronous API built on top of the paho-mqtt library. The current stable version is 2.5.1. It maintains a regular release cadence, with minor and patch releases occurring every few weeks to months, and a major version (3.0.0) currently in alpha with significant breaking changes.","status":"active","version":"2.5.1","language":"en","source_language":"en","source_url":"https://github.com/empicano/aiomqtt","tags":["asyncio","mqtt","client","messaging"],"install":[{"cmd":"pip install aiomqtt","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core MQTT client library that aiomqtt wraps for asyncio compatibility. (Note: aiomqtt v3.0.0-alpha.1 and later replace this with 'mqtt5'.)","package":"paho-mqtt","optional":false}],"imports":[{"symbol":"Client","correct":"from aiomqtt import Client"},{"symbol":"Message","correct":"from aiomqtt import Message"},{"symbol":"Topic","correct":"from aiomqtt import Topic"}],"quickstart":{"code":"import asyncio\nimport os\nfrom aiomqtt import Client, Topic\n\nasync def main():\n    mqtt_host = os.environ.get(\"MQTT_HOST\", \"localhost\")\n    mqtt_port = int(os.environ.get(\"MQTT_PORT\", 1883))\n    mqtt_topic = os.environ.get(\"MQTT_TOPIC\", \"test/topic\")\n\n    print(f\"Connecting to mqtt://{mqtt_host}:{mqtt_port}...\")\n    async with Client(hostname=mqtt_host, port=mqtt_port) as client:\n        await client.subscribe(Topic(mqtt_topic, qos=1))\n        print(f\"Subscribed to '{mqtt_topic}'. Waiting for messages...\")\n\n        async for message in client.messages:\n            # For aiomqtt v2.x, message is an aiomqtt.Message object.\n            # For aiomqtt v3.x+, message will be an mqtt5.PublishPacket object.\n            print(f\"Received message on topic '{message.topic}': {message.payload.decode()}\")\n            if message.payload.decode() == \"exit\":\n                print(\"Received 'exit' message, shutting down.\")\n                break\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to connect to an MQTT broker, subscribe to a topic, and asynchronously receive messages. It uses environment variables for host, port, and topic, falling back to defaults. Replace `MQTT_HOST` with your broker's address (e.g., `mqtt.eclipseprojects.io`)."},"warnings":[{"fix":"Review the migration guide for v3.0.0 when upgrading. Code written for v2.x will not be compatible without significant changes.","message":"aiomqtt v3.0.0 introduces extensive breaking changes. It replaces the `paho-mqtt` dependency with `mqtt5`, drops support for MQTTv3.1/3.1.1, makes all `Client` parameters keyword-only, changes message types from `aiomqtt.Message` to `mqtt5.PublishPacket`, alters the `publish` payload argument from `payload=` keyword to a positional `bytes` argument, and makes `client.messages` a method (`client.messages()`).","severity":"breaking","affected_versions":"3.0.0-alpha.1 and later"},{"fix":"Upgrade to aiomqtt v2.2.0 or newer. If stuck on an older version, ensure `client.messages` is only consumed once per subscription or connection lifecycle.","message":"The `client.messages` asynchronous iterator was not reusable prior to version 2.2.0. If you tried to iterate over it multiple times or in different contexts, it would only yield messages during the first iteration.","severity":"gotcha","affected_versions":"<2.2.0"},{"fix":"Upgrade to aiomqtt v2.3.1 or newer. For custom asyncio integrations, ensure your environment is compatible with `get_running_loop()` (Python 3.7+).","message":"Internal usage of `asyncio.get_event_loop()` was replaced with `asyncio.get_running_loop()` to align with modern asyncio best practices. While this primarily affects internal library behavior, users relying on specific event loop interactions with older Python versions or less common asyncio setups might observe subtle differences.","severity":"deprecated","affected_versions":"<2.3.1"},{"fix":"Upgrade to aiomqtt v2.5.1 or newer. If you must use `tls_insecure=True`, ensure `tls_params` are correctly configured for insecure connections, or avoid using both simultaneously if possible.","message":"Combining `tls_params` with `tls_insecure=True` could lead to connection failures in versions prior to 2.5.1.","severity":"gotcha","affected_versions":"<2.5.1"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}