matrix-python 1.5.0a0

An easy-to-use Matrix bot framework designed for quick development and minimal setup

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

---

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.

• Minimal setup — install and have a working bot running in minutes
• Event-driven — async/await API reacting to any Matrix room event
• Command system — decorator-based commands with automatic argument parsing
• Extensions — split your bot into modules as it grows

Quickstart

Requirements: Python 3.10+

pip install matrix-python

Using a virtual environment is strongly recommended:

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install matrix-python

Create a config.yml:

USERNAME: "@yourbot:matrix.org"
PASSWORD: "your_password"

from matrix import Bot, Context

bot = Bot()


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


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

Send !ping in any room the bot is in, it will reply Pong!.

Where to go next

• Guides — step-by-step tutorials covering commands, events, checks, extensions, and more
• Reference — complete API documentation for every class and function
• Examples — ready-to-run example bots demonstrating common patterns

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
• Hop into our Matrix or Discord and say hi!

Please read the CONTRIBUTING.md and follow the code of conduct.

License

Released under the MIT License.