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-rc4 for Browser, Node, React Native, Android, iOS, and Agent clients. Use ghcr.io/xmtp/backend:8.0.0-rc4 for the backend. Pin the exact release candidate version. The published Browser 7 and Node 6 packages use an earlier backend API.

Browser, Node, React Native, and Agent packages

Use the package for your platform:

Platform	Package
Browser	`@xmtp/[email protected]`
Node	`@xmtp/[email protected]`
React Native	`@xmtp/[email protected]`
Agent	`@xmtp/[email protected]`

Run one command from your app directory. These commands install the Browser SDK. For Node, React Native, or Agent, replace the entire package specifier @xmtp/[email protected] with its package and version from the table.

npm install --save-exact @xmtp/[email protected]

pnpm add --save-exact @xmtp/[email protected]

yarn add --exact @xmtp/[email protected]

bun add --exact @xmtp/[email protected]

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-rc4")
    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-rc4 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-rc4")

// 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 Hermes and New Architecture. Bare React Native requires iOS 15.1 or Android API 24. Expo development builds require iOS 16.4 on iOS. The package ships arm64 iOS device/simulator libraries and all four Android ABIs. See React Native and Expo for consumer validation targets, native setup, and rebuild steps. Expo Go is not supported.

The app owns secure key persistence. Reuse the same optional 32-byte storage.encryptionKey and native database location between launches.

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.