{"id":4104,"library":"matrix-nio","title":"Nio: A Python Matrix Client Library","description":"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.","status":"active","version":"0.25.2","language":"en","source_language":"en","source_url":"https://github.com/matrix-nio/matrix-nio","tags":["Matrix","client","async","chat","messaging","E2EE","sans-IO"],"install":[{"cmd":"pip install matrix-nio","lang":"bash","label":"Base installation (includes async HTTP support)"},{"cmd":"pip install \"matrix-nio[e2e]\"","lang":"bash","label":"With End-to-End Encryption (E2EE) support"}],"dependencies":[{"reason":"Provides the asynchronous HTTP client implementation for the asyncio layer.","package":"aiohttp","optional":false},{"reason":"Required for end-to-end encryption (E2EE) support, which itself depends on the native libolm C library (version 3.x).","package":"python-olm","optional":true}],"imports":[{"symbol":"AsyncClient","correct":"from nio import AsyncClient"},{"symbol":"RoomMessageText","correct":"from nio import RoomMessageText"},{"symbol":"LoginResponse","correct":"from nio import LoginResponse"}],"quickstart":{"code":"import asyncio\nimport os\nfrom nio import AsyncClient, RoomMessageText, LoginResponse\n\nasync def message_callback(room, event):\n    \"\"\"Callback for when a message is received.\"\"\"\n    print(f\"Message in {room.display_name} from {room.user_name(event.sender)}: {event.body}\")\n\nasync def main():\n    homeserver = os.environ.get(\"MATRIX_HOMESERVER\", \"https://matrix.org\")\n    user_id = os.environ.get(\"MATRIX_USER_ID\", \"@your_username:matrix.org\")\n    password = os.environ.get(\"MATRIX_PASSWORD\", \"your_password\")\n    device_name = os.environ.get(\"MATRIX_DEVICE_NAME\", \"nio-bot\")\n\n    if user_id == \"@your_username:matrix.org\" or password == \"your_password\":\n        print(\"Please set MATRIX_HOMESERVER, MATRIX_USER_ID, and MATRIX_PASSWORD environment variables.\")\n        return\n\n    client = AsyncClient(homeserver, user_id)\n    client.add_event_callback(message_callback, RoomMessageText)\n\n    print(f\"Attempting to login as {user_id}...\")\n    try:\n        response = await client.login(password, device_name=device_name)\n        if isinstance(response, LoginResponse):\n            print(f\"Logged in successfully with device ID: {response.device_id}\")\n        else:\n            print(f\"Login failed: {response.message}\")\n            return\n\n        print(\"Starting sync loop...\")\n        await client.sync_forever(timeout=30000)\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n    finally:\n        await client.close()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or later.","message":"Python 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.","severity":"breaking","affected_versions":">=0.21.0"},{"fix":"Migrate any custom logging setup from `logbook` to Python's built-in `logging` module.","message":"The `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`.","severity":"breaking","affected_versions":">=0.21.0"},{"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]`.","message":"End-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`.","severity":"gotcha","affected_versions":"All versions with E2EE"},{"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.","message":"As 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.","severity":"breaking","affected_versions":">=0.25.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}