The idiomatic asyncio MQTT client#

Write code like this:

Publish

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

Subscribe

async with Client("test.mosquitto.org") as client:
    await client.subscribe("humidity/#")
    async for message in client.messages:
        print(message.payload)

aiomqtt combines the stability of the time-proven paho-mqtt library with an idiomatic asyncio interface:

  • No more callbacks! đź‘Ť

  • No more return codes (welcome to the MqttError)

  • Graceful disconnection (forget about on_unsubscribe, on_disconnect, etc.)

  • Supports MQTT versions 5.0, 3.1.1 and 3.1

  • Fully type-hinted

  • Did we mention no more callbacks?

Installation#

aiomqtt can be installed via pip install aiomqtt. The only dependency is paho-mqtt.

If you can’t wait for the latest version, you can install aiomqtt directly from GitHub with:

pip install git+https://github.com/sbtinstruments/aiomqtt

Note for Windows users#

Since Python 3.8, the default asyncio event loop is the ProactorEventLoop. Said loop doesn’t support the add_reader method that is required by aiomqtt. Please switch to an event loop that supports the add_reader method such as the built-in SelectorEventLoop:

# Change to the "Selector" event loop if platform is Windows
if sys.platform.lower() == "win32" or os.name.lower() == "nt":
    from asyncio import set_event_loop_policy, WindowsSelectorEventLoopPolicy
    set_event_loop_policy(WindowsSelectorEventLoopPolicy())
# Run your async application as usual
asyncio.run(main())

License#

This project is licensed under the BSD 3-clause License.

Note that the underlying paho-mqtt library is dual-licensed. One of the licenses is the Eclipse Distribution License v1.0, which is almost identical to the BSD 3-clause License. The only differences are:

  • One use of “COPYRIGHT OWNER” (EDL) instead of “COPYRIGHT HOLDER” (BSD)

  • One use of “Eclipse Foundation, Inc.” (EDL) instead of “copyright holder” (BSD)

Contributing#

We’re very happy about contributions to aiomqtt! ✨ You can get started by reading CONTRIBUTING.md.

Versioning#

This project adheres to Semantic Versioning. Breaking changes will only occur in major X.0.0 releases.

Changelog#

The changelog lives in CHANGELOG.md. It follows the principles of Keep a Changelog.