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
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.fixUpgrade 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`.fixMigrate 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`.fixInstall `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.fixEnsure 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.
fixInstall 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.
fixEnsure 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'.
fixUpdate '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.
fixInitialize '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.
fixCheck 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).