https://github.com/code-society-lab/matrixpy
A simple, developer-friendly library to create Matrix bots.
https://github.com/code-society-lab/matrixpy
bot matrix matrix-bot matrix-org python
Last synced: 6 days ago
JSON representation
A simple, developer-friendly library to create Matrix bots.
- Host: GitHub
- URL: https://github.com/code-society-lab/matrixpy
- Owner: Code-Society-Lab
- License: gpl-3.0
- Created: 2025-05-24T22:14:01.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-03-02T05:52:10.000Z (about 2 months ago)
- Last Synced: 2026-03-02T10:09:27.695Z (about 2 months ago)
- Topics: bot, matrix, matrix-bot, matrix-org, python
- Language: Python
- Homepage: https://github.com/Code-Society-Lab/matrixpy/wiki
- Size: 166 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[
](https://matrixpy.codesociety.xyz/guides/introduction/)
[
](https://matrixpy.codesociety.xyz/reference/bot/)
[](https://discord.gg/code-society-823178343943897088)
[](https://matrix.to/#/%23codesociety:matrix.org)
[](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/tests.yml)
[](https://pypi.org/project/matrix-python/)
[](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/codeql.yml)
[](https://securityscorecards.dev/viewer/?uri=github.com/Code-Society-Lab/matrixpy)
---
Matrix.py is a lightweight and intuitive Python library to build bots on the [Matrix protocol](https://matrix.org). 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+
```bash
pip install matrix-python
```
Using a virtual environment is strongly recommended:
```bash
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install matrix-python
```
Create a `config.yml`:
```yaml
USERNAME: "@yourbot:matrix.org"
PASSWORD: "your_password"
```
```python
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**](https://matrixpy.codesociety.xyz/guides/introduction/) — step-by-step tutorials covering commands,
events, checks, extensions, and more
- [**Reference**](https://matrixpy.codesociety.xyz/reference/bot/) — complete API documentation for every class and
function
- [**Examples**](https://matrixpy.codesociety.xyz/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](https://github.com/Code-Society-Lab/matrixpy/issues)
- [Open a pull request](https://github.com/Code-Society-Lab/matrixpy/blob/main/CONTRIBUTING.md)
- Hop into our [Matrix](https://matrix.to/#/%23codesociety:matrix.org)
or [Discord](https://discord.gg/code-society-823178343943897088) and say hi!
Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) and follow the [code of conduct](./CODE_OF_CONDUCT.md).
## License
Released under the [MIT License](https://github.com/Code-Society-Lab/matrixpy/blob/main/LICENSE).