{"id":6312,"library":"asyncio-mqtt","title":"asyncio-mqtt","description":"asyncio-mqtt is an idiomatic Python asyncio wrapper built around the robust paho-mqtt library. It provides a modern `async`/`await` interface, eliminating the need for callbacks and simplifying MQTT communication in asynchronous applications. The library aims for graceful disconnection and clear error handling via `MqttError`. As of version 0.16.2, it is stable but has since been superseded by `aiomqtt` (version 1.0.0+), which is the actively maintained successor. The project adheres to Semantic Versioning, with significant API changes expected before a 1.0.0 release (which occurred under the `aiomqtt` name).","status":"deprecated","version":"0.16.2","language":"en","source_language":"en","source_url":"https://github.com/sbtinstruments/asyncio-mqtt","tags":["mqtt","asyncio","networking","iot"],"install":[{"cmd":"pip install asyncio-mqtt","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core MQTT client functionality, asyncio-mqtt acts as an asynchronous wrapper.","package":"paho-mqtt","optional":false}],"imports":[{"symbol":"Client","correct":"from asyncio_mqtt import Client"},{"symbol":"MqttError","correct":"from asyncio_mqtt import MqttError"}],"quickstart":{"code":"import asyncio\nfrom asyncio_mqtt import Client, MqttError\n\nasync def publish_message():\n    async with Client(\"test.mosquitto.org\") as client:\n        await client.publish(\"my/topic\", payload=b\"Hello, asyncio-mqtt!\")\n        print(\"Published 'Hello, asyncio-mqtt!' to my/topic\")\n\nasync def subscribe_and_receive():\n    async with Client(\"test.mosquitto.org\") as client:\n        async with client.filtered_messages(\"my/topic\") as messages:\n            await client.subscribe(\"my/topic\")\n            print(\"Subscribed to my/topic. Waiting for messages...\")\n            async for message in messages:\n                print(f\"Received: {message.payload.decode()} on topic {message.topic}\")\n                # For quickstart, exit after one message\n                break\n\nasync def main():\n    await asyncio.gather(publish_message(), subscribe_and_receive())\n\nif __name__ == \"__main__\":\n    # Note for Windows users: Since Python 3.8, the default asyncio event loop is the\n    # ProactorEventLoop. It doesn't support the add_reader method required by asyncio-mqtt.\n    # Switch to SelectorEventLoop if encountering issues.\n    # import sys\n    # if sys.platform.lower() == \"win32\" or os.name.lower() == \"nt\":\n    #     from asyncio import set_event_loop_policy, WindowsSelectorEventLoopPolicy\n    #     set_event_loop_policy(WindowsSelectorEventLoopPolicy())\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates both publishing and subscribing to an MQTT topic using `asyncio-mqtt`'s context manager pattern. It connects to a public test broker, publishes a single message, and then subscribes to the same topic to receive it. On Windows, a specific `asyncio` event loop policy might be required for Python 3.8+."},"warnings":[{"fix":"Migrate your project to use `aiomqtt`. Uninstall `asyncio-mqtt` and install `aiomqtt` (`pip install aiomqtt`). Update import statements from `from asyncio_mqtt import ...` to `from aiomqtt import ...`.","message":"The `asyncio-mqtt` project was renamed to `aiomqtt`. Version `0.17.0` of `asyncio-mqtt` was yanked due to the rename causing breaking changes for users of an older `aiomqtt` library. Users are strongly encouraged to migrate to `aiomqtt` (version `1.0.0` or higher) for continued maintenance and new features.","severity":"breaking","affected_versions":"<1.0.0 (under `asyncio-mqtt` name)"},{"fix":"Update exception handling to catch `MqttError` instead of `asyncio.TimeoutError` for MQTT-specific operations. `try...except MqttError:`","message":"As of `aiomqtt` (the successor to `asyncio-mqtt`) v1.0.0, `asyncio.TimeoutError` is no longer raised for timeout-related issues in `Client.subscribe`, `unsubscribe`, or `publish`. Instead, `MqttError` is raised.","severity":"breaking","affected_versions":">=1.0.0 (of `aiomqtt` equivalent)"},{"fix":"Switch to the `SelectorEventLoop` at the start of your application. Example: `import asyncio; asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())`.","message":"On Windows, for Python 3.8 and later, the default `ProactorEventLoop` does not support the `add_reader` method required by `asyncio-mqtt`. This can lead to runtime errors or the client not functioning correctly.","severity":"gotcha","affected_versions":"All versions on Python 3.8+ on Windows"},{"fix":"Always use `async with Client(...)` to ensure proper connection and disconnection handling.","message":"The library strongly advocates for the use of `async with Client(...)` context managers for connecting and disconnecting. Manual `client.connect()` and `client.disconnect()` methods are discouraged and may lead to connection management issues and footguns related to graceful disconnection.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If your code previously expected only the payload, update it to access `message.payload` and other attributes as needed. E.g., `async for message in messages: print(message.payload.decode())`.","message":"A change was introduced where `client.filtered_messages()` and `client.unfiltered_messages()` yield the full `MQTTMessage` object (from `paho-mqtt`) instead of just the payload. This provides access to `topic`, `qos`, `retain` flags, etc.","severity":"breaking","affected_versions":">=0.16.2"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}