amqtt/README.md

[![MIT licensed](https://img.shields.io/github/license/Yakifo/amqtt?style=plastic)](https://amqtt.readthedocs.io/en/latest/)
[![CI](https://github.com/Yakifo/amqtt/actions/workflows/ci.yml/badge.svg?branch=rc)](https://github.com/Yakifo/amqtt/actions/workflows/ci.yml)
[![CodeQL](https://github.com/Yakifo/amqtt/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Yakifo/amqtt/actions/workflows/codeql-analysis.yml)
[![Read the Docs](https://img.shields.io/readthedocs/amqtt/v0.11.0?style=plastic&logo=readthedocs)](https://amqtt.readthedocs.io/)
[![Discord](https://dcbadge.limes.pink/api/server/https://discord.gg/S3sP6dDaF3?style=plastic)](https://discord.gg/S3sP6dDaF3)
![Python Version](https://img.shields.io/pypi/pyversions/amqtt?style=plastic&logo=python&logoColor=yellow)
![Python Wheel](https://img.shields.io/pypi/wheel/amqtt?style=plastic)
[![PyPI](https://img.shields.io/pypi/v/amqtt?style=plastic&logo=python&logoColor=yellow)](https://pypi.org/project/amqtt/)

![docs/assets/amqtt.svg](https://raw.githubusercontent.com/Yakifo/amqtt/refs/tags/v0.11.0/docs/assets/amqtt.svg)

`aMQTT` is an open source [MQTT](http://www.mqtt.org) broker and client[^1], natively implemented with Python's [asyncio](https://docs.python.org/3/library/asyncio.html).

## Features

- Full set of [MQTT 3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) protocol specifications
- Communication over TCP and/or websocket, including support for SSL/TLS
- Support QoS 0, QoS 1 and QoS 2 messages flow
- Client auto-reconnection on network lost
- Functionality expansion; plugins included: authentication and `$SYS` topic publishing

## Installation

`amqtt` is available on [PyPI](https://pypi.python.org/pypi/amqtt)

```bash
$ pip install amqtt
```

## Documentation

Available on [Read the Docs](http://amqtt.readthedocs.org/).

## Containerization

Launch from [DockerHub](https://hub.docker.com/repositories/amqtt)

```shell
$ docker run -d -p 1883:1883 amqtt/amqtt:latest
```

## Testing

The `amqtt` project runs a test aMQTT broker/server at [test.amqtt.io](https://test.amqtt.io) which supports: MQTT, MQTT over TLS, websocket, secure websockets.


## Support

Bug reports, patches and suggestions welcome! Just [open an issue](https://github.com/Yakifo/amqtt/issues/new) or join the [discord community](https://discord.gg/S3sP6dDaF3).

## Python Version Compatibility

| Version | hbmqtt compatibility | Supported Python Versions |
| ------- | -------------------- | ------------------------- |
| 0.10.x  | yes [^2]             | 3.7 - 3.9                 |
| 0.11.x  | no [^3]              | 3.10 - 3.13               |


[^1]: Forked from [HBMQTT](https://github.com/beerfactory/hbmqtt) after it was deprecated by the original author.

[^2]: drop-in replacement

[^3]: module renamed and small API differences
switching from gitter to discord 2025-06-11 16:43:25 +00:00			`[![MIT licensed](https://img.shields.io/github/license/Yakifo/amqtt?style=plastic)](https://amqtt.readthedocs.io/en/latest/)`
			`[![CI](https://github.com/Yakifo/amqtt/actions/workflows/ci.yml/badge.svg?branch=rc)](https://github.com/Yakifo/amqtt/actions/workflows/ci.yml)`
update to amqtt logo. revisions to amqtt docs 2025-05-21 16:37:02 +00:00			`[![CodeQL](https://github.com/Yakifo/amqtt/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Yakifo/amqtt/actions/workflows/codeql-analysis.yml)`
fixed broken link 2025-06-25 23:49:50 +00:00			`[![Read the Docs](https://img.shields.io/readthedocs/amqtt/v0.11.0?style=plastic&logo=readthedocs)](https://amqtt.readthedocs.io/)`
			`[![Discord](https://dcbadge.limes.pink/api/server/https://discord.gg/S3sP6dDaF3?style=plastic)](https://discord.gg/S3sP6dDaF3)`
switching from gitter to discord 2025-06-11 16:43:25 +00:00			`![Python Version](https://img.shields.io/pypi/pyversions/amqtt?style=plastic&logo=python&logoColor=yellow)`
			`![Python Wheel](https://img.shields.io/pypi/wheel/amqtt?style=plastic)`
			`[![PyPI](https://img.shields.io/pypi/v/amqtt?style=plastic&logo=python&logoColor=yellow)](https://pypi.org/project/amqtt/)`
README update 2021-03-13 13:53:37 +00:00
fix readme file image src so it works on pypi 2025-06-17 22:12:05 +00:00			`![docs/assets/amqtt.svg](https://raw.githubusercontent.com/Yakifo/amqtt/refs/tags/v0.11.0/docs/assets/amqtt.svg)`
fix formatting of badges 2021-03-16 07:44:33 +00:00
amqtt.io (#206) * ignoring all files and adding back was causing confusion * adding in amqtt.io website * adding amqtt logo * removing mobile version of the dashboard menu * minor change to naming of logo * adding functionality to display statistics from amqtt broker * adding content about configuration * separating amqtt.io from test.amqtt.io * adding link to the test server page * remove unneeded state * docker file for building image * separating docker build into two phases to minimize image size. add documentation for docker launch / configure * updating docs with references to docker image * adding missing icons * adding docker compose samples. updating classifiers and version * fixing uv lock file version identifier * tweaking test.amqtt.io page to include broker start and uptime. fix project links. add gitter icon * missing image * update to include 'client' 2025-06-11 15:49:09 +00:00			`aMQTT` is an open source [MQTT](http://www.mqtt.org) broker and client[^1], natively implemented with Python's [asyncio](https://docs.python.org/3/library/asyncio.html).
README update 2021-03-13 13:53:37 +00:00
convert rst files to md 2025-05-21 13:53:46 +00:00			`## Features`
add pypi badges 2021-03-13 17:32:44 +00:00
update to amqtt logo. revisions to amqtt docs 2025-05-21 16:37:02 +00:00			`- Full set of [MQTT 3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) protocol specifications`
			`- Communication over TCP and/or websocket, including support for SSL/TLS`
Typo fix 2015-11-04 21:32:21 +00:00			`- Support QoS 0, QoS 1 and QoS 2 messages flow`
Move read to restructured 2015-11-04 20:36:47 +00:00			`- Client auto-reconnection on network lost`
consistent description in readme file 2025-06-12 18:28:50 +00:00			- Functionality expansion; plugins included: authentication and `$SYS` topic publishing
Move read to restructured 2015-11-04 20:36:47 +00:00
updating client documentation by converting rst format into google docstring params, including examples from reference file 2025-05-22 01:59:12 +00:00			`## Installation`
Move read to restructured 2015-11-04 20:36:47 +00:00
update to amqtt logo. revisions to amqtt docs 2025-05-21 16:37:02 +00:00			`amqtt` is available on [PyPI](https://pypi.python.org/pypi/amqtt)
Add gitter channel link 2016-03-07 14:41:00 +00:00
convert rst files to md 2025-05-21 13:53:46 +00:00			```bash
			`$ pip install amqtt`
			```
README update 2021-03-13 13:53:37 +00:00
updating client documentation by converting rst format into google docstring params, including examples from reference file 2025-05-22 01:59:12 +00:00			`## Documentation`
Move read to restructured 2015-11-04 20:36:47 +00:00
updating client documentation by converting rst format into google docstring params, including examples from reference file 2025-05-22 01:59:12 +00:00			`Available on [Read the Docs](http://amqtt.readthedocs.org/).`

separating docker build into two phases to minimize image size. add documentation for docker launch / configure 2025-06-09 18:32:55 +00:00			`## Containerization`

amqtt.io (#206) * ignoring all files and adding back was causing confusion * adding in amqtt.io website * adding amqtt logo * removing mobile version of the dashboard menu * minor change to naming of logo * adding functionality to display statistics from amqtt broker * adding content about configuration * separating amqtt.io from test.amqtt.io * adding link to the test server page * remove unneeded state * docker file for building image * separating docker build into two phases to minimize image size. add documentation for docker launch / configure * updating docs with references to docker image * adding missing icons * adding docker compose samples. updating classifiers and version * fixing uv lock file version identifier * tweaking test.amqtt.io page to include broker start and uptime. fix project links. add gitter icon * missing image * update to include 'client' 2025-06-11 15:49:09 +00:00			`Launch from [DockerHub](https://hub.docker.com/repositories/amqtt)`
separating docker build into two phases to minimize image size. add documentation for docker launch / configure 2025-06-09 18:32:55 +00:00
			```shell
			`$ docker run -d -p 1883:1883 amqtt/amqtt:latest`
			```

path tweaks for v0.11.0 release 2025-06-17 14:58:48 +00:00			`## Testing`

			The `amqtt` project runs a test aMQTT broker/server at [test.amqtt.io](https://test.amqtt.io) which supports: MQTT, MQTT over TLS, websocket, secure websockets.


updating client documentation by converting rst format into google docstring params, including examples from reference file 2025-05-22 01:59:12 +00:00			`## Support`
using the README file as the index overview 2025-05-21 15:46:46 +00:00
switching from gitter to discord 2025-06-11 16:43:25 +00:00			`Bug reports, patches and suggestions welcome! Just [open an issue](https://github.com/Yakifo/amqtt/issues/new) or join the [discord community](https://discord.gg/S3sP6dDaF3).`
using the README file as the index overview 2025-05-21 15:46:46 +00:00
updating client documentation by converting rst format into google docstring params, including examples from reference file 2025-05-22 01:59:12 +00:00			`## Python Version Compatibility`
update to amqtt logo. revisions to amqtt docs 2025-05-21 16:37:02 +00:00
fixed broken link 2025-06-25 23:49:50 +00:00			`\| Version \| hbmqtt compatibility \| Supported Python Versions \|`
			`\| ------- \| -------------------- \| ------------------------- \|`
			`\| 0.10.x \| yes [^2] \| 3.7 - 3.9 \|`
			`\| 0.11.x \| no [^3] \| 3.10 - 3.13 \|`
update to amqtt logo. revisions to amqtt docs 2025-05-21 16:37:02 +00:00

			`[^1]: Forked from [HBMQTT](https://github.com/beerfactory/hbmqtt) after it was deprecated by the original author.`
fixed broken link 2025-06-25 23:49:50 +00:00
update to amqtt logo. revisions to amqtt docs 2025-05-21 16:37:02 +00:00			`[^2]: drop-in replacement`
fixed broken link 2025-06-25 23:49:50 +00:00
update to amqtt logo. revisions to amqtt docs 2025-05-21 16:37:02 +00:00			`[^3]: module renamed and small API differences`