{"id":8306,"library":"matrix-client","title":"Matrix Client SDK","description":"The `matrix-client` library is a Client-Server SDK for the Matrix protocol, providing functionality to interact with Matrix homeservers. It is currently at version 0.4.0 and releases are infrequent, often addressing breaking changes or incompatibilities with the Matrix protocol or Synapse homeserver.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/matrix-org/matrix-python-sdk","tags":["matrix","chat","client","sdk","messaging"],"install":[{"cmd":"pip install matrix-client","lang":"bash","label":"Standard Install"},{"cmd":"pip install matrix-client[e2e]","lang":"bash","label":"Install with E2E Encryption Support"}],"dependencies":[{"reason":"Native library required for experimental End-to-End Encryption (E2E) features. Must be installed system-wide (v3.0.0+).","package":"libolm","optional":true}],"imports":[{"symbol":"MatrixClient","correct":"from matrix_client.client import MatrixClient"},{"note":"Typically accessed via MatrixClient methods, not directly instantiated.","symbol":"Room","correct":"from matrix_client.room import Room"}],"quickstart":{"code":"import os\nfrom matrix_client.client import MatrixClient\n\nHOMESERVER_URL = os.environ.get('MATRIX_HOMESERVER_URL', 'https://matrix.org')\nUSERNAME = os.environ.get('MATRIX_USERNAME', 'test_user')\nPASSWORD = os.environ.get('MATRIX_PASSWORD', 'test_password')\nROOM_ID_OR_ALIAS = os.environ.get('MATRIX_ROOM', '#test:matrix.org') # Replace with a valid room\n\ntry:\n    # For matrix-client v0.4.0+, `use_authorization_header=True` is recommended\n    # for better compatibility with modern Synapse versions.\n    client = MatrixClient(HOMESERVER_URL, use_authorization_header=True)\n    client.login(username=USERNAME, password=PASSWORD)\n    print(f\"Successfully logged in as {USERNAME}\")\n\n    # Try to join a room\n    room = client.join_room(ROOM_ID_OR_ALIAS)\n    print(f\"Successfully joined room: {room.name} ({room.room_id})\")\n\n    # Send a message\n    room.send_text(\"Hello from matrix-client Python SDK!\")\n    print(\"Sent a test message.\")\n\n    # Logout\n    client.logout()\n    print(\"Logged out.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure MATRIX_HOMESERVER_URL, MATRIX_USERNAME, MATRIX_PASSWORD, and MATRIX_ROOM are set correctly and are valid.\")","lang":"python","description":"This quickstart demonstrates how to log into a Matrix homeserver, join a room, send a message, and then log out. Ensure `MATRIX_HOMESERVER_URL`, `MATRIX_USERNAME`, `MATRIX_PASSWORD`, and `MATRIX_ROOM` environment variables are set or replaced with actual values."},"warnings":[{"fix":"Upgrade to `matrix-client` v0.4.0 or newer. When initializing `MatrixClient`, it's recommended to set `use_authorization_header=True` for better compatibility with modern Synapse versions.","message":"Older versions of `matrix-client` (prior to 0.4.0) are incompatible with Synapse homeservers running version 1.38.0 or newer, leading to connection issues or failed API calls.","severity":"breaking","affected_versions":"<0.4.0"},{"fix":"First, install `libolm` (version 3.0.0 or higher) system-wide on your operating system. Then, install the Python E2E dependencies using `pip install matrix-client[e2e]`.","message":"End-to-end encryption (E2E) support is experimental, disabled by default, and requires specific native `libolm` (v3.0.0+) and Python dependencies (`matrix-client[e2e]`) to be installed.","severity":"gotcha","affected_versions":"0.4.0+"},{"fix":"Refer to the latest documentation for preferred ways to access and modify properties (e.g., `room.name` instead of `room.get_name()`), avoiding deprecated methods.","message":"Many getter and setter methods (e.g., `get_name()`, `set_topic()`) were deprecated in v0.3.2 in favor of direct attribute access or alternative methods.","severity":"deprecated","affected_versions":"0.3.2+"},{"fix":"Ensure your code uses the `/sync` API calls via the client's methods, rather than making direct calls to the deprecated endpoints, which may no longer be supported by homeservers.","message":"The Matrix API endpoints `/initialSync` and `/events` were deprecated in v0.0.4, with `/sync` becoming the standard for event retrieval.","severity":"deprecated","affected_versions":"0.0.4+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade to `matrix-client` v0.4.0 and initialize `MatrixClient(homeserver_url, use_authorization_header=True)`. Double-check your username and password.","cause":"This error often occurs when `matrix-client` prior to v0.4.0 attempts to connect to Synapse homeservers v1.38.0+ due to changes in authorization header handling, or simply incorrect login credentials.","error":"matrix_client.client.MatrixRequestError: 403 Forbidden: Invalid homeserver or credentials."},{"fix":"First, install `libolm` (version 3.0.0 or higher) system-wide on your operating system. Then, install the Python E2E dependencies: `pip install matrix-client[e2e]`.","cause":"You are attempting to use experimental End-to-End Encryption (E2E) features, but the necessary native `libolm` library and/or its Python wrapper have not been installed.","error":"ModuleNotFoundError: No module named 'olm'"},{"fix":"Access the attribute directly (e.g., `room.name`) instead of using `room.get_name()`. Consult the library's documentation for current API methods.","cause":"You are using a deprecated getter method (e.g., `get_name()`) that was removed or replaced by direct attribute access.","error":"AttributeError: 'Room' object has no attribute 'get_name'"}]}