README.md

The idiomatic asyncio MQTT Client 🙌

Write code like this:

Publisher

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

Subscriber

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

asyncio-mqtt combines the stability of the time-proven paho-mqtt library with a modern, asyncio-based interface.

• No more callbacks! 👍
• No more return codes (welcome to the MqttError)
• Graceful disconnection (forget about on_unsubscribe, on_disconnect, etc.)
• Compatible with async code
• Fully type-hinted
• Did we mention no more callbacks?

The whole thing is less than 900 lines of code.

---

Read the documentation at sbtinstruments.github.io/asyncio-mqtt

---

Installation

asyncio-mqtt can be installed via pip install asyncio-mqtt. It requires Python 3.7+ to run. The only dependency is paho-mqtt.

If you can't wait for the latest version and want to install directly from GitHub, use:

pip install git+https://github.com/sbtinstruments/asyncio-mqtt

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 asyncio-mqtt. Please switch to an event loop that supports the add_reader method such as the built-in SelectorEventLoop:

# Change to the "Selector" event loop
asyncio.set_event_loop_policy(asyncio.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 so-called Eclipse Distribution License v1.0. It is almost word-for-word 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 happy about your contributions to the project!

You can get started by reading the CONTRIBUTING.md.

Versioning

This project adheres to Semantic Versioning.

Expect API changes until we reach version 1.0.0. After 1.0.0, breaking changes will only occur in a major release (e.g., 2.0.0, 3.0.0, etc.).

Changelog

The changelog lives in the CHANGELOG.md document. It adheres to the principles of Keep a Changelog.

Related projects

Is asyncio-mqtt not what you're looking for? There are a few other clients you can try:

• paho-mqtt — Own protocol implementation. Synchronous.
  
• gmqtt — Own protocol implementation. Asynchronous.
  
• fastapi-mqtt — Asynchronous wrapper around gmqtt. Simplifies integration in your FastAPI application.
  
• amqtt — Own protocol implementation. Asynchronous. Includes a broker.
  
• mqttools — Own protocol implementation. Asynchronous.
  
• trio-paho-mqtt — Asynchronous wrapper around paho-mqtt (similar to asyncio-mqtt). Based on trio instead of asyncio.