Install the XMTP SDK

Install the SDK for your platform. All SDKs use a backend URL. See Create a client for client options and Run the backend if you operate the backend.

Install a package

Use 8.0.0-rc1 for Browser, Node, Android, iOS, and Agent clients. Use ghcr.io/xmtp/backend:8.0.0-rc1 for the backend. Pin the exact release candidate version. The published Browser 7 and Node 6 packages use an earlier backend API.

Browser, Node, and Agent packages

Use the package for your platform:

Platform	Package
Browser	`@xmtp/browser-sdk@8.0.0-rc1`
Node	`@xmtp/node-sdk@8.0.0-rc1`
Agent	`@xmtp/agent-sdk@8.0.0-rc1`

Run one command from your app directory. These commands install the Browser SDK. For Node or Agent, replace @xmtp/browser-sdk with the package name in the table.

npm install --save-exact @xmtp/browser-sdk@8.0.0-rc1

pnpm add --save-exact @xmtp/browser-sdk@8.0.0-rc1

yarn add --exact @xmtp/browser-sdk@8.0.0-rc1

bun add --exact @xmtp/browser-sdk@8.0.0-rc1

Install the complete package. Keep the generated source, native or WASM bindings, and runtime assets together.

Android package

Add the XMTP Maven artifact to your app module:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
        isCoreLibraryDesugaringEnabled = true
    }
}
dependencies {
    implementation("org.xmtp:android:8.0.0-rc1")
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

Import uniffi.xmtp_sdk.*. Keep the generated sources and JNI libraries from the same release. An older network SDK cannot use this backend.

Swift package

Add libxmtp as a Swift package in Xcode. Select the ios-8.0.0-rc1 tag and add the XmtpSdk product to your app. For a Swift package, add these dependency and target entries:

// In Package.dependencies:
.package(url: "https://github.com/xmtp/libxmtp.git", revision: "ios-8.0.0-rc1")

// In your app target's dependencies:
.product(name: "XmtpSdk", package: "libxmtp")

The release package supplies the matching native binary. Import XmtpSdk.

Platform prerequisites

Use Node.js 22.12.0 or later for package tooling and a bundler that supports WebAssembly. The Browser SDK stores its database in browser storage and does not encrypt it. Do not pass storage.encryptionKey; the Browser SDK rejects it.

Use Node.js 22.12.0 or later. If you use database encryption, pass a 32-byte storage.encryptionKey. Keep that key and the database location stable between launches. Omitting the key selects unencrypted storage.

Use Android API 23 or later and Java 17 for the SDK build. Provide an Android Context. Set ClientOptions.backend to BackendSource.Options(BackendOptions(url = backendUrl)). Set the database location and optional 32-byte key in StorageOptions. Call suspend methods from a coroutine. End each client in withContext(NonCancellable).

Use Swift 6.1 or later. The package supports iOS 14 or later and macOS 11 or later. Pass BackendOptions(url:) through ClientOptions.backend. Use StorageOptions for the database location. Pass a securely generated or caller-stored 32-byte encryptionKey for persistent storage. Keep the key and reuse it when reopening the database. Omitting it selects unencrypted storage. Call async methods from an async context.