Matrix Rust SDK: client library with encryption, sync and UI layers

Three crates for three levels of abstraction: crypto, mid-level SDK and UI

Matrix protocol work involves encryption state, sync queues and room state. The SDK splits those responsibilities across three crates that the README designates as fit for direct dependencies. Everything else in the workspace is internal, structured as crates for organizational purposes and to improve compilation times.

The lowest layer is matrix-sdk-crypto: an encryption state machine with no network I/O. It handles end-to-end encryption for Matrix clients and libraries, and because it performs no networking itself, it can be embedded in environments where the network layer is controlled elsewhere. A crypto tutorial at docs.rs/matrix-sdk-crypto/ walks through it step by step.

The middle layer is matrix-sdk, the general-purpose client library for bots, custom integrations and lower-level clients. Its examples/ directory covers 15 use cases: autojoin, backups, command_bot, cross_signing_bootstrap, custom_events, emoji_verification, get_profiles, getting_started, image_bot, login, oauth_cli, persist_session, qr-login, secret_storage and timeline.

The top layer is matrix-sdk-ui, targeting full-featured UI clients that want minimal setup. Sitting above matrix-sdk, it provides the higher-level sync timeline and room state abstractions. The reference client, multiverse, lives in the labs/ directory and shows the full UI layer in action.

Adding matrix-sdk to a Cargo project and the 1.96 toolchain requirement

The crate is published on crates.io under the name matrix-sdk. Before adding it, two constraints in the workspace Cargo.toml set the floor for any caller.

resolver = "3"

[workspace.package]
rust-version = "1.96"

The resolver version 3 and the 1.96 minimum are both hard requirements: an older Cargo or Rust toolchain will fail to build. Verifying your toolchain version before pulling in the crate saves debugging time.

For matrix-sdk-ui, the crate name changes but the source is the same: add matrix-sdk-ui as a Cargo dependency and consult its API docs at docs.rs/matrix-sdk-ui/. Pulling in matrix-sdk-ui brings matrix-sdk as a transitive dependency, so the full client chain is included without a separate explicit dependency.

For matrix-sdk-crypto as a standalone library, the crate is matrix-sdk-crypto on crates.io. A crypto tutorial is available at docs.rs/matrix-sdk-crypto/latest/matrix_sdk_crypto/tutorial/index.html, described in the README as a step-by-step introduction to the encryption state machine.

All three crates are distributed together and documented individually on docs.rs. The README badges link to the API reference pages for matrix-sdk, matrix-sdk-ui and matrix-sdk-crypto.

matrix-sdk-crypto: encryption state machine with no network layer

The design decision that sets matrix-sdk-crypto apart is the deliberate absence of networking. It operates as a pure state machine that processes encryption operations without initiating or receiving any network calls. That constraint makes it suitable for environments where the network layer belongs to the caller or to a separate runtime.

For clients built on matrix-sdk or matrix-sdk-ui, encryption is handled transparently through matrix-sdk-crypto under the hood. Those clients do not need to add matrix-sdk-crypto to their direct dependencies; it arrives as a transitive dependency.

The standalone use case is embedding E2E encryption in a client or library that does not use the full SDK. A library that wants Matrix E2EE without the sync logic, the room state tracking or the HTTP client can take matrix-sdk-crypto alone.

The bindings/ directory includes matrix-sdk-crypto-ffi, which wraps the crypto layer for foreign language environments. That crate is separate from matrix-sdk-ffi, which wraps the higher-level SDK. An environment that needs only the encryption layer can take a smaller FFI dependency and leave out the full client stack.

Bindings for Swift, Kotlin, JavaScript and Node.js via bindings/

The README names 4 supported binding targets: Swift, Kotlin, JavaScript and Node.js. The bindings/ directory contains 2 FFI crates: matrix-sdk-ffi, which wraps the higher-level SDK, and matrix-sdk-crypto-ffi, which wraps only the encryption layer.

The FFI layer uses uniffi, maintained in the repository at uniffi-bindgen/. uniffi generates language bindings from Rust code. That mechanism is how Element X iOS and Element X Android are built: both apps use the Matrix Rust SDK through its Swift and Kotlin bindings.

A developer building a native mobile app in Swift or Kotlin can use the SDK without writing Rust. The binding crates are workspace members but are excluded from the default build. Running cargo build from the workspace root does not compile the bindings; they require explicit invocation.

Python, Go, PHP and other languages are not listed in the README. A team that needs Matrix in one of those languages must either maintain an FFI wrapper around one of the existing binding crates or use a different client library entirely. That is a genuine gap for teams not on the supported target list.

Default workspace build excludes bindings, labs and the multiverse client

A detail in Cargo.toml worth noting is the default-members field: it lists benchmarks and crates/*, nothing else. Bindings, examples, labs, testing and uniffi-bindgen are workspace members but are not default members.

A developer who clones the repository and runs cargo build from the root compiles the SDK crates and the benchmarks. The FFI bindings, the multiverse reference client in labs/, the test helpers in testing/, and the examples are all excluded from that default build.

That matters for matrix-sdk-ui specifically. The README points to multiverse as the reference example for the UI layer: "Check out our reference client, multiverse, for an example." Multiverse lives at labs/multiverse. To build it and use it as a guide, a developer must target that path explicitly, not simply run cargo build at the root.

For the examples directory, the same applies. Each example under examples/ is a workspace member, and building any of them requires targeting the specific example rather than relying on the default build. The examples/README.md file is available at the top of the examples directory.

Element X and Fractal use this SDK in production: what that means for integrators

The README states the library is "considered production ready" and names four clients that build on it: Element X on iOS, Element X on Android, Fractal, and iamb. Element sponsors and maintains the project. Each of those clients is independently verifiable.

Element's sponsorship has a practical implication for the feature roadmap. Features that serve Element X have a direct path to the project. Features for other use cases, such as compact bots or embedded crypto-only integrations, depend on contributor effort and maintainer attention. The CONTRIBUTING.md file and the GitHub issue tracker are the channels for raising those.

What the SDK does not handle is the application layer above the protocol. Room UIs, notification handling, media galleries and accessibility are caller responsibilities. The SDK delivers synced message timelines, room state and encryption outcomes; the caller decides what to do with them.

Available under Apache-2.0, the latest release is matrix-sdk 0.19.1, published on 2026-09-18.

When matrix-sdk adds more than needed: bots, non-Rust targets and runtime constraints

A simple integration that only pushes notifications to a Matrix room does not require the full SDK. A caller can send a Matrix message over HTTP directly using a homeserver URL and an access token. Adding matrix-sdk introduces a Tokio runtime dependency, a sync machinery, and all the state management that comes with a full client, for a job a single HTTP call handles.

The second mismatch is teams whose target language has no binding. The bindings support Swift, Kotlin, JavaScript and Node.js. A team that needs Matrix in Python, Go, Ruby or another unlisted language has to maintain its own FFI wrapper or use a different library.

The third is environments that cannot run an async Tokio runtime. matrix-sdk-crypto's no-network design removes that constraint for pure encryption use, but matrix-sdk and matrix-sdk-ui are async clients. The workspace dependencies include async-compat version 0.2.5, which can bridge between runtimes, but the README does not document a supported path for callers using a different async executor. Teams in that situation are outside the explicitly documented scope.

For bot authors who do need sync and room state but want a lighter surface, matrix-sdk with the examples/command_bot example is the documented starting point, not matrix-sdk-ui.

Editorial conclusion

Matrix Rust SDK is the right choice for Rust developers who want the Matrix protocol handled for them: room state, sync and E2E encryption without writing against the raw spec. Use matrix-sdk for bots and lighter clients, matrix-sdk-ui when you need a full sync timeline, and matrix-sdk-crypto alone when only the E2E layer is needed. Skip it when your target language has no binding in the bindings/ directory. Before adopting, confirm your toolchain meets the 1.96 minimum, then build multiverse explicitly from labs/ to check whether matrix-sdk-ui's timeline model matches your UI layer.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. matrix-org/matrix-rust-sdk on GitHub
4. README
5. Releases