asyncio-mqtt

0.16.2 · deprecated · verified Wed Apr 15

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).

Warnings

breaking 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.
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 ...`.
breaking 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.
Fix: Update exception handling to catch `MqttError` instead of `asyncio.TimeoutError` for MQTT-specific operations. `try...except MqttError:`
gotcha 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.
Fix: Switch to the `SelectorEventLoop` at the start of your application. Example: `import asyncio; asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())`.
gotcha 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.
Fix: Always use `async with Client(...)` to ensure proper connection and disconnection handling.
breaking 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.
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())`.

Install

pip install asyncio-mqtt Install stable version

Imports

Client
```
from asyncio_mqtt import Client
```
MqttError
```
from asyncio_mqtt import MqttError
```

Quickstart

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+.

import asyncio
from asyncio_mqtt import Client, MqttError

async def publish_message():
    async with Client("test.mosquitto.org") as client:
        await client.publish("my/topic", payload=b"Hello, asyncio-mqtt!")
        print("Published 'Hello, asyncio-mqtt!' to my/topic")

async def subscribe_and_receive():
    async with Client("test.mosquitto.org") as client:
        async with client.filtered_messages("my/topic") as messages:
            await client.subscribe("my/topic")
            print("Subscribed to my/topic. Waiting for messages...")
            async for message in messages:
                print(f"Received: {message.payload.decode()} on topic {message.topic}")
                # For quickstart, exit after one message
                break

async def main():
    await asyncio.gather(publish_message(), subscribe_and_receive())

if __name__ == "__main__":
    # Note for Windows users: Since Python 3.8, the default asyncio event loop is the
    # ProactorEventLoop. It doesn't support the add_reader method required by asyncio-mqtt.
    # Switch to SelectorEventLoop if encountering issues.
    # import sys
    # if sys.platform.lower() == "win32" or os.name.lower() == "nt":
    #     from asyncio import set_event_loop_policy, WindowsSelectorEventLoopPolicy
    #     set_event_loop_policy(WindowsSelectorEventLoopPolicy())
    asyncio.run(main())

view raw JSON →