Skip to content

matrix.py

A simple, developer-friendly library to create powerful Matrix bots.

image image

Static Badge Join Discord Join Matrix Tests CodeQL Advanced OpenSSF Scorecard

Matrix.py is a lightweight and intuitive Python library to build bots on the Matrix protocol. It provides a clean, decorator-based API similar to popular event-driven frameworks, allowing developers to focus on behavior rather than boilerplate.

Key Features

  • Minimal setup, easy to extend
  • Event-driven API using async/await
  • Clean command registration
  • Automatic event handler registration
  • Built on matrix-nio

Quickstart

Requirements

  • Python 3.10+
pip install matrix-python

If you plan on contributing to matrix.py, we recommend to install the development libraries:

pip install -e .[dev]

Note: It is recommended to use a virtual environment when installing python packages.

from matrix import Bot, Context

bot = Bot()


@bot.command("ping")
async def ping(ctx: Context):
    await ctx.reply("Pong!")


bot.start(config="config.yml")

Documentation - Examples

Contributing

We welcome everyone to contribute!

Whether it's fixing bugs, suggesting features, or improving the docs - every bit helps.

  • Submit an issue
  • Open a pull request
  • Or just hop into our Matrix or Discord server and say hi!

If you intend to contribute, please read the CONTRIBUTING.md first. Additionally, * every contributor* is expected to follow the code of conduct.

License

This project is licensed under the terms of MIT license.