Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# The idiomatic asyncio MQTT client 🙌

Write code like this:

Publish

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

Subscribe

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

## Key features

- 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

    pip install aiomqtt

The only dependency is paho-mqtt.

If you can’t wait for the latest version, install 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 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

See CHANGELOG.md, which follows the principles of Keep a Changelog.