matrix-python

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matrix_python-1.0.1.tar.gz (96.2 kB view details)

Uploaded Aug 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

matrix_python-1.0.1-py3-none-any.whl (39.9 kB view details)

Uploaded Aug 4, 2026 Python 3

File details

Details for the file matrix_python-1.0.1.tar.gz.

File metadata

Download URL: matrix_python-1.0.1.tar.gz
Upload date: Aug 4, 2026
Size: 96.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for matrix_python-1.0.1.tar.gz
Algorithm	Hash digest
SHA256	`00e4ce904f60735a4c91ca734d60c4e2193d73ef50bbe4ca3b27f94e7fcbf08b`
MD5	`688b8aecfe2a89bae21b9b08ce2bcde6`
BLAKE2b-256	`2a73f7b5554f06228e1750374969ad13d66d7b4d986174f2d3667d4e02a9bfd2`

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrix_python-1.0.1.tar.gz:

Publisher: publish.yml on Code-Society-Lab/matrixpy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: matrix_python-1.0.1.tar.gz
- Subject digest: 00e4ce904f60735a4c91ca734d60c4e2193d73ef50bbe4ca3b27f94e7fcbf08b
- Sigstore transparency entry: 2340663618
- Sigstore integration time: Aug 4, 2026
Source repository:
- Permalink: Code-Society-Lab/matrixpy@8e6ddd04d05e12973a33577270dfdf4ee6034b89
- Branch / Tag: refs/tags/1.0.1
- Owner: https://github.com/Code-Society-Lab
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8e6ddd04d05e12973a33577270dfdf4ee6034b89
- Trigger Event: release