Skip to main content
A simple, developer-friendly library to create powerful Matrix bots.
matrix.py

Join Discord Join Matrix Tests PyPI 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.

  • 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.

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

License

Released under the MIT License.

Metadata

Release files for matrix-python 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for matrix-python 1.0.2
File Size Uploaded Provenance Actions
matrix_python-1.0.2.tar.gz 96.7 kB With provenance Details for matrix_python-1.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for matrix-python 1.0.2
File Interpreter ABI Platform Actions
matrix_python-1.0.2-py3-none-any.whl Python 3 none any Details for matrix_python-1.0.2-py3-none-any.whl

Total release size: 136.7 kB

Release files / matrix_python-1.0.2.tar.gz

Download URL matrix_python-1.0.2.tar.gz
Size 96.7 kB
Tags Source
SHA-256 checksum
How to use checksums
2b9e4d9ce213ab72527a15cea7a8e81559a4ee5093cb1a7e5d91908923b9579e
BLAKE2b-256 checksum
How to use checksums
81c90817dc1f376eeecd90c2d84fc4315937de88935418b044642e123f58eb05
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / matrix_python-1.0.2-py3-none-any.whl

Download URL matrix_python-1.0.2-py3-none-any.whl
Size 39.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f50cf6ee954efa92a824a49854e57d3d0043b08d7a2c124e7be4b770c8cb955f
BLAKE2b-256 checksum
How to use checksums
62eace6b0d41f6a0f981b5a678404fb265eee8375e495671bb60311b5bdac70a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for matrix-python 1.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for matrix_python-1.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page