mqttwarn turns MQTT topics into messages on every service you use

A subscription, a transformation and a delivery

The one line description is that mqttwarn subscribes to any number of MQTT topics and publishes the received payloads to one or more notification services, after optionally applying sophisticated transformations. Three ideas in one sentence, and each is a decision you make in the configuration. The subscription side is ordinary MQTT, so the tool works with whatever broker you already run, with Eclipse Mosquitto the one the documentation recommends. The transformation step is where the tool earns its keep, since the payload on a topic is rarely in the shape a notification service wants, so a message can be reshaped before it is sent, which is what turns a raw sensor reading into a sentence. The delivery side is the plugin system, and the routing target is a notification service rather than another MQTT topic, so the tool is a bridge out of the broker into the world of push messages, email, chat and everything else. The documentation points at a diagram early on, and the picture is a fair summary of the whole design.

Seventy plugins, and Apprise on top of them

The plugin count is the headline number, over seventy notification handler plugins covering a wide range of services, and the documentation says the project is open to further contributions and publishes an alphabetical catalogue of them. The list of extras in the packaging shows the flavour of those targets, and it is a long one. There is a native push service, an Apprise integration, an Asterisk telephony client, an NSCA passive monitoring client, a desktop notification client, a Toot paste service, a chromecast target, a DNS update target, a chat client, a Google Sheets client, a MySQL publisher, an NNTP publisher, a PostgreSQL publisher, a Prowl push client, a Redis publisher, a round robin database client and a serial port client. On top of that sits the Apprise integration, which brings Apprise's own list of more than eighty notification services. The practical consequence is that the plugin count is not the interesting number, since the effective coverage is over a hundred and fifty services, and the interesting number is how many of them you can enable without dragging a heavyweight client library into your environment.

Installing with pip, and the extras that decide your footprint

The installation is a pip install, and the interesting part is the extras:

pip install --upgrade mqttwarn
pip install --upgrade 'mqttwarn[xmpp]'

The first line is the base install, the second adds the extra for one specific service, and the documentation shows that you can name several at once, with an example that combines the Apprise, Asterisk, NSCA, desktop notification, paste and XMPP extras in a single command. That is the right shape for the way the tool is used, because a notification router that installs every client library by default becomes a dependency problem for everyone who does not need them. The base install itself is small, with paho-mqtt for the protocol, jinja2 for templating, requests for the HTTP based targets, simplejson, attrs, funcy, docopt and six, plus importlib metadata and resources for the older Python versions. The requirement is Python 3.x or PyPy 3.x, and a broker is needed, with additional modules required for specific plugins as the setup file documents.

One ini file, two environment variables

The configuration is a single ini file, and the tool finds it through an environment variable. Running the program with no arguments is the whole interactive service:

export MQTTWARNINI=/etc/mqttwarn/acme.ini
export MQTTWARNLOG=/var/log/mqttwarn.log
mqttwarn

`MQTTWARNINI` points at the configuration file and `MQTTWARNLOG` at the log file, and neither is mandatory, since the tool has a default location for both. The Compose file in the repository shows the intended deployment shape, with a `mqttwarn.ini` and a `funcs.py` kept in a directory on the host that is mounted into the container at `/etc/mqttwarn`, and the compose file also shows how to obtain a starter configuration, by downloading the basic example `mqttwarn.ini` from the repository. The `functions` setting points at the custom functions file, which is where your own transformation code goes, and that is the extension point that turns the tool from a fixed set of routes into something you can adapt, since the transformations in the configuration can call functions you write.

A daemon, a library call, or a development sandbox

There are three ways to run the thing, and the documentation covers each. The first is as a system daemon, and the `etc/` directory of the repository holds worked examples for systemd with a `mqttwarn.service` file, for traditional init, for OpenRC and for Supervisor with a `supervisor.ini`, so the packaging for the four common init systems is already written. The second is standalone invocation, which the documentation points at when you want to call a notification plugin directly from your own program or when you are debugging a single plugin, which is a genuinely useful capability since most of the difficulty in this tool is in a transformation rather than in the subscription. The third is the development sandbox, an install in development mode for hacking on the code itself. The repository also ships an `examples/` directory with worked configurations, and the names describe the use cases, an Alexa example, an Arduino temperature example, Frigate, Hiveeyes, the Homie protocol, a media player, OwnTracks with ntfy, a toggle named warntoggle, and a Zabbix IoT example.

The container runs as a user and mounts its configuration

There are three Dockerfiles in the repository, one for the standard image, one for the full image and one for a variant with Slack, and the Compose file uses the full image. The standard Dockerfile is a good example of a container that is careful about what it does. It starts from a slim Python 3.14 image on Trixie, installs the build prerequisites, creates a system group and a system user called mqttwarn, chowns the configuration directory to it, installs the package, and then removes the build dependencies and the source tree again so they do not ship in the image. The runtime then switches to that unprivileged user with a `USER` instruction, declares `/etc/mqttwarn` as a volume so the configuration survives a container replacement, sets `MQTTWARNINI` to the path inside that volume, and starts the program. The Compose file follows the same idea, mapping a host directory into the container and mounting the host's local time file read only so the log timestamps are right, and it sets `restart: always`. The two images published to the GitHub Container Registry are the standard and the full one, the difference being how many service plugins are baked in.

Tooling, tests and the licence

The packaging configuration shows a project with a modern toolchain and an opinionated one. The build is setuptools with versioningit deriving the version from the git tag, the default tag being a placeholder zero version. Formatting is black with a line length of 120 and import sorting is isort with the black profile, linting is ruff with the same line length and with the bare except rule turned off, and there is a separate type checker configuration with two deliberate exclusions, a test file with invalid syntax and a syslog module that behaves differently on Windows. The pytest configuration is thorough, with coverage reported to the terminal, to XML and to an HTML report, the test paths covering the examples, the package and the tests directory, strict xfail handling, and a marker called e2e reserved for the tests that need a real MQTT broker, which is the right way to separate a fast suite from an integration one. The licence is EPL-2.0, and the documentation also records the legal points that matter if you deploy this, since MQTT is a trademark of the OASIS consortium and Eclipse Mosquitto is a trademark of the Eclipse Foundation. The project is copyright Jan-Piet Mens and contributors, and the release cadence shows 0.36.0 and 0.36.1 both on 2026-07-12 after 0.35.0 from 2023, with the last push to the repository on 2026-07-22.

Editorial conclusion

mqttwarn suits a home automation or IoT setup where a device publishes to an MQTT topic and something should happen when it does, since the topic to service mapping is all the tool asks of you, and it suits anyone who wants a notification destination the vendor of the device has never heard of. It is a poor fit if you need durable delivery, since the design is a subscription and a call rather than a queue with retries, and it is a poor fit if you want something other than notifications, since the routing targets are notification services by design. Before you deploy it, check four things: the extras you need for the services you care about, since each plugin pulls its own client library, the configuration file location, since the container image expects it at `/etc/mqttwarn/mqttwarn.ini` on a mounted volume, and the broker you point it at, with Eclipse Mosquitto the recommended one, and the state of the project, with 0.36.1 published on 2026-07-12 and the last push on 2026-07-22.

Frequently asked questions

Official sources

1. License: EPL-2.0
2. mqtt-tools/mqttwarn on GitHub
3. Project website
4. README
5. Releases