asyncio-mqtt

What it is and what it does

asyncio-mqtt is a thin, modern wrapper around paho-mqtt that replaces callback-based MQTT code with async/await patterns. Instead of defining on_message, on_connect, and on_disconnect callbacks, you write straightforward async context managers and async for loops to subscribe, publish, and handle messages. It handles connection lifecycle automatically and raises MqttError exceptions instead of returning error codes, making error handling more Pythonic.

The package is designed for developers building asyncio-based applications—web services, IoT clients, or any async Python code that needs MQTT messaging. It depends only on paho-mqtt for the underlying protocol implementation and typing-extensions for type hints, keeping the wrapper itself under 700 lines of code. It supports Python 3.7 through 3.11 and runs on Linux, macOS, and Windows (with a minor event-loop configuration on Windows).

Use it for:

• Building async web services (FastAPI, Starlette) that need to publish or subscribe to MQTT topics without blocking request handlers.
• Writing IoT device clients that listen for commands and publish sensor readings using native async/await instead of managing callbacks.
• Integrating MQTT into async event-driven applications where you want message handling to fit naturally into the asyncio task model.
• Sharing a single MQTT connection across multiple concurrent async functions without creating separate clients or managing complex callback state.
• Filtering and routing incoming MQTT messages by topic pattern (e.g., humidity/outside, +/inside) within a single async loop.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides an async/await interface to MQTT messaging, wrapping paho-mqtt with modern Python asyncio patterns instead of callbacks.

Yes. The package solves a real pain point—callback-free MQTT in async Python—with minimal dependencies, active maintenance, and no known vulnerabilities. Install friction is low and the BSD license is permissive. The only caveat is the Windows event-loop gotcha, which is well-documented and easily worked around. Suitable for production use in asyncio applications.

Install

asyncio-mqtt on PyPI

pip install asyncio-mqtt

uv add asyncio-mqtt

poetry add asyncio-mqtt

Installing asyncio-mqtt

Before you install

Low friction: pure Python wheel with only two runtime dependencies (paho-mqtt and typing-extensions). Actively maintained with recent commits; last release was over 2 years ago but repository shows ongoing activity.

License in practice

BSD 3-Clause License (permissive) allows commercial and private use with minimal restrictions—include a copy of the license and you're clear.

Quickstart

pip install asyncio-mqtt

import asyncio_mqtt as aiomqtt

async def main():
    async with aiomqtt.Client("test.mosquitto.org") as client:
        await client.publish("humidity/outside", payload=0.38)

asyncio.run(main())

On Windows with Python 3.8+, the default ProactorEventLoop does not support add_reader(); you must switch to SelectorEventLoop via asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy()) before running your async code.

Verify before relying

• Whether the package is still actively maintained—last release was June 2023 but last commit shown is April 2026; clarify release cadence.
• Performance characteristics under high message throughput or with many concurrent subscriptions.
• Compatibility with MQTT 5.0 features beyond what paho-mqtt 1.x provides.

Package facts

Evidence: asyncio_mqtt-0.16.2-py3-none-any.whl

Keywords: mqtt, async, asyncio, paho-mqtt, wrapper

Tags

More Internet packages