Skip to content

Home

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

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 file:

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

Or use environment variables:

USERNAME: ${MATRIX_USERNAME}
PASSWORD: ${MATRIX_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.

    Start with the Introduction

  • Reference

    Complete API documentation for every class and function in the library.

    Browse the Reference

  • Examples

    Ready-to-run example bots demonstrating common patterns and use cases.

    View Examples

  • Source Code

    Browse the source, open issues, and contribute on GitHub.

    View on GitHub

Contributing

We welcome everyone to contribute! Whether it's fixing bugs, suggesting features, or improving the docs — every bit helps.

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

License

Released under the MIT License.