Registry / communication / matrix-nio

matrix-nio

JSON →
library0.26.0pypypi✓ verified 23d ago

matrix-nio is a multilayered Python client library for the Matrix communication protocol, designed according to sans I/O principles. It provides a full-featured asyncio layer, leveraging aiohttp for network operations, and supports various Matrix features including end-to-end encryption. The library is actively maintained, with regular releases (current version 0.25.2) and ongoing feature development.

pip install matrix-nio
INSTALL
IMPORT
SIG · MATRIX-NIO
M
matrix-nio
communicationpythonv0.26.0
Install
6.5s avg
Import
1835ms
Disk
50MB
Pass rate
9/ 10
Env Coverage9 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.26.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 7.3s
py 3.11
✓ —
✓ 5.8s
py 3.12
✓ —
✓ 5.35s
py 3.13
✓ —
✓ 5.45s
py 3.9
1/2 runs
✓ 8.55s
50MB installed
● package 50MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AsyncClient
from nio import AsyncClient
RoomMessageText
from nio import RoomMessageText
LoginResponse
from nio import LoginResponse

This quickstart demonstrates how to initialize an `AsyncClient`, log in, register a callback for text messages, and start an endless sync loop to receive events. It uses environment variables for sensitive login details.

import asyncio import os from nio import AsyncClient, RoomMessageText, LoginResponse async def message_callback(room, event): """Callback for when a message is received.""" print(f"Message in {room.display_name} from {room.user_name(event.sender)}: {event.body}") async def main(): homeserver = os.environ.get("MATRIX_HOMESERVER", "https://matrix.org") user_id = os.environ.get("MATRIX_USER_ID", "@your_username:matrix.org") password = os.environ.get("MATRIX_PASSWORD", "your_password") device_name = os.environ.get("MATRIX_DEVICE_NAME", "nio-bot") if user_id == "@your_username:matrix.org" or password == "your_password": print("Please set MATRIX_HOMESERVER, MATRIX_USER_ID, and MATRIX_PASSWORD environment variables.") return client = AsyncClient(homeserver, user_id) client.add_event_callback(message_callback, RoomMessageText) print(f"Attempting to login as {user_id}...") try: response = await client.login(password, device_name=device_name) if isinstance(response, LoginResponse): print(f"Logged in successfully with device ID: {response.device_id}") else: print(f"Login failed: {response.message}") return print("Starting sync loop...") await client.sync_forever(timeout=30000) except Exception as e: print(f"An error occurred: {e}") finally: await client.close() if __name__ == "__main__": asyncio.run(main())
matrix-nio --version
Debug
Known issues
breakingPython 3.7 support was dropped in matrix-nio version 0.21.0. Users on older Python versions must upgrade to Python 3.8 or newer.
fix
Upgrade your Python environment to 3.8 or later.
affects: >=0.21.0
breakingThe `logbook` library was replaced with Python's standard `logging` module in version 0.21.0. Custom logging configurations using `logbook` will break and need to be adapted to `logging`.
fix
Migrate any custom logging setup from `logbook` to Python's built-in `logging` module.
affects: >=0.21.0
gotchaEnd-to-end encryption (E2EE) requires the `python-olm` package, which in turn needs the `libolm` C library (version 3.x) to be installed on your system. This C library is not installed automatically by `pip`.
fix
Install `libolm` (version 3.x) via your system's package manager (e.g., `apt-get install libolm-dev` on Debian/Ubuntu, `brew install libolm` on macOS) before installing `matrix-nio[e2e]`.
affects: All versions with E2EE
breakingAs of version 0.25.1, `matrix-nio` uses authenticated media access (Authorization header) and requires the homeserver to be compliant with Matrix v1.11. This was introduced to restore support for matrix.org, which disabled unauthenticated media access.
fix
Ensure your Matrix homeserver is compliant with Matrix v1.11 or newer to avoid issues with media access, especially when interacting with matrix.org.
affects: >=0.25.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nio'
The 'matrix-nio' package is not installed or not properly installed in the Python environment.
fix
Install the package using pip: 'pip install matrix-nio'.
ImportError: cannot import name 'AsyncClient' from 'nio'
The 'AsyncClient' class is not found in the 'nio' module, possibly due to an incorrect import statement or version mismatch.
fix
Ensure the correct import statement: 'from nio import AsyncClient'.
AttributeError: 'AsyncClient' object has no attribute 'login'
The 'login' method is not available in the 'AsyncClient' class, possibly due to using an outdated version of 'matrix-nio'.
fix
Update 'matrix-nio' to the latest version: 'pip install --upgrade matrix-nio'.
TypeError: __init__() missing 1 required positional argument: 'homeserver'
The 'AsyncClient' class constructor requires the 'homeserver' argument, which was not provided.
fix
Initialize 'AsyncClient' with the required 'homeserver' argument: 'client = AsyncClient(homeserver)'.
ValueError: No JSON object could be decoded
The response from the Matrix server is not a valid JSON object, possibly due to network issues or server errors.
fix
Check the network connection and ensure the Matrix server is operational.
Upgrade
Version history
0.26.0latest on PyPI · released Jul 23, 2026
Audit
Dependencies
aiohttprequiredProvides the asynchronous HTTP client implementation for the asyncio layer.
python-olmoptionalRequired for end-to-end encryption (E2EE) support, which itself depends on the native libolm C library (version 3.x).
Agent activity
28 hits · last 30 days
node
26
OpenAI (training)
1
Resources
matrix-nio — pip install matrix-nio · libregistry