Skip to main content

Python SDKs for Matrix

Multiple Python libraries are available for Matrix development.

SDK Options​

LibraryStyleE2EEBest For
matrix-nioAsync✅Bots, async apps
mautrix-pythonAsync✅Bridges, advanced
matrix-clientSync❌Simple scripts

matrix-nio​

The most popular async Python SDK.

Installation​

pip install "matrix-nio[e2e]"

Basic Usage​

import asyncio
from nio import AsyncClient, RoomMessageText

async def message_callback(room, event):
    print(f"{room.display_name}: {event.sender} - {event.body}")

async def main():
    client = AsyncClient("https://matrix.example.com", "@bot:example.com")

    await client.login("password")

    client.add_event_callback(message_callback, RoomMessageText)

    await client.sync_forever(timeout=30000)

asyncio.run(main())

Send Message​

await client.room_send(
    room_id="!roomid:example.com",
    message_type="m.room.message",
    content={
        "msgtype": "m.text",
        "body": "Hello, Matrix!"
    }
)

E2EE Support​

from nio import AsyncClient, AsyncClientConfig
from nio.store import SqliteStore

config = AsyncClientConfig(store_sync_tokens=True)
client = AsyncClient(
    "https://matrix.example.com",
    "@bot:example.com",
    store_path="./store",
    config=config
)

await client.login("password")

# Keys are automatically managed

File Upload​

from nio import UploadResponse

with open("image.png", "rb") as f:
    response = await client.upload(f, content_type="image/png")

await client.room_send(
    room_id,
    "m.room.message",
    {
        "msgtype": "m.image",
        "body": "image.png",
        "url": response.content_uri
    }
)

mautrix-python​

Powers mautrix bridges, good for advanced use.

Installation​

pip install mautrix

Basic Usage​

from mautrix.client import Client
from mautrix.types import EventType

client = Client(
    mxid="@bot:example.com",
    base_url="https://matrix.example.com"
)

@client.on(EventType.ROOM_MESSAGE)
async def handler(evt):
    print(evt.content.body)

await client.start(filter=None)

Comparison​

matrix-nio​

# Simpler API
await client.room_send(room_id, "m.room.message", content)

mautrix​

# More explicit
await client.send_message(room_id, content)

Resources​

Next: Specification Overview →