Downloads
Get the bitHuman SDK: install commands for every surface plus the full device and platform support matrix.
Get the SDK
One engine (libessence) drives every surface. Pick the install path that matches what you’re building — they all read the same .imx avatar file and produce identical frames.
bitHuman CLI (no code)
The fastest way to see an avatar talk. The same Rust binary ships through all three channels — byte-identical. macOS arm64 and Linux (x86_64 + aarch64).
Homebrew (recommended on Apple Silicon)
brew install bithuman-product/bithuman/bithuman-cliUniversal installer (macOS Apple Silicon + Linux, no Python required)
curl -fsSL https://raw.githubusercontent.com/bithuman-product/homebrew-bithuman/main/install.sh | shPyPI sibling wheel (same Rust binary, Python-friendly) — macOS Apple Silicon only
pip install bithuman-cliNote The
bithuman-cliPyPI wheel is published for macOS Apple Silicon (arm64) only. On Linux there is nobithuman-cliwheel — use the universal installer above (it drops the same byte-identical binary).
Verify the install:
bithuman --version
# libessence 1.19.1 ABI 7
# bithuman 2.3.25
bithuman doctor # full host + key + cache checkSee the CLI reference for all subcommands (run, render, info, pull, list, doctor, init, login/logout, and mcp).
Python SDK (library) — GA
pip install bithuman is the on-device avatar runtime library — from bithuman import AsyncBithuman. macOS arm64 + Linux x86_64 / aarch64 (manylinux_2_28, glibc), Python 3.10–3.14.
pip install bithumanmacOS note The 2.3.4 macOS wheels are tagged for macOS 26+ (arm64). On older macOS versions pip reports
No matching distribution found— upgrade to macOS 26+, or build from source / contact hello@bithuman.ai.
Add the LiveKit agent integration:
pip install livekit-plugins-bithuman pillowNote The plugin currently imports Pillow without declaring it — install
pillowalongside (upstream fix pending with LiveKit), orfrom livekit.plugins import bithumanfails withModuleNotFoundError: No module named 'PIL'.
See the Python SDK guide.
Swift / Apple SDK — Preview
On-device real-time avatar for iOS, iPadOS, and macOS via SwiftPM. Apple Silicon only.
In Xcode: File → Add Package Dependencies… → paste
https://github.com/bithuman-product/bithuman-sdk-public.git → pick 0.8.2
→ attach the bitHumanKit product. The package wraps a pre-compiled
XCFramework with all third-party deps statically linked — zero transitive
SwiftPM dependencies.
The product import is import bitHumanKit. See the Swift SDK guide.
Android / Kotlin SDK — Beta
Self-contained Android AAR via Maven Central. arm64-v8a, Android 10+.
// app/build.gradle.kts
dependencies {
implementation("ai.bithuman:sdk:2.3.6")
}See the Kotlin SDK guide.
JavaScript / TypeScript — Preview
A cloud client for browser and Node apps. Preview status — APIs may change.
Note — not yet available.
@bithuman/sdkis not published to npm (npm install @bithuman/sdk404s today) and has no public source package yet. For a browser/Node integration today, drive a cloud avatar over LiveKit. Track the changelog for the release; the command below is the form it will take.
npm install @bithuman/sdk # not available yetREST API
No install required. Authenticate with the api-secret header against https://api.bithuman.ai. See the API reference and the quickstart.
Note Flutter is currently a reference app only (in
bithuman-apps), not a published code SDK. See community for how to follow its progress.
What ships in 2.3
2.3.0 is the first split-wheel release: the Python library (pip install bithuman) and the CLI binary (pip install bithuman-cli or brew install bithuman-product/bithuman/bithuman-cli) are now separate packages. Pre-2.3 PyPI bundled both — 2.2.x with the bundled CLI is still on PyPI and works, but consider it legacy; pin to 2.3+ for new projects.
| Platform | CLI binary | Python wheel | Swift SDK | Kotlin SDK |
|---|---|---|---|---|
| macOS arm64 (M-series) | Homebrew + bithuman-cli wheel | bithuman (3.10–3.14) | SwiftPM | — |
| macOS x86_64 (Intel) | Pending | Pending (1.x was last) | — | — |
| Linux x86_64 | Universal installer (tarball) | bithuman (manylinux) | — | — |
| Linux aarch64 | Universal installer (tarball) | bithuman (manylinux) | — | — |
| Windows | Not shipping (use WSL2) | Not shipping (1.9.0 was last) | — | — |
| iOS / iPadOS | — | — | SwiftPM | — |
| Android | — | — | — | Maven Central ai.bithuman:sdk |
macOS-Intel and Windows are tracked but not part of the 2.3 cut. If you’re stuck on either, the 1.x line still has Windows wheels and a macOS-Intel build — pin the whole Python stack there until those targets graduate into the 2.x distribution.
Current shipping versions
| Artifact | Latest version | Channel | libessence ABI |
|---|---|---|---|
Python SDK (bithuman) | 2.3.4 | PyPI | v7 |
Swift SDK (bitHumanKit) | 0.8.2 | SwiftPM | v7 |
Kotlin SDK (ai.bithuman:sdk) | 2.3.6 | Maven Central | v7 |
bitHuman CLI (bithuman-cli) | 2.3.25 | Homebrew (macOS) · PyPI bithuman-cli (macOS Apple Silicon only) · universal installer (macOS Apple Silicon + Linux) | v7 |
Artifacts with matching ABI are interoperable even if their headline versions differ. Mixing surfaces in one project — for example the Swift SDK on iOS plus the Python bithuman 2.3.4 wheel on the backend — is supported and tested as long as the ABI columns line up.
Device and platform support
Two avatar models, different hardware floors. For a side-by-side feature comparison, see models. At a glance, by device:
| Device | Essence? | Expression? | SDKs |
|---|---|---|---|
| iPhone 16 Pro+ | Yes | Preview (prefer Essence) | Swift |
| iPad Pro M4+ | Yes | Yes | Swift |
| Mac (Apple Silicon) | Yes | Yes (M3+) | Swift, Python, CLI |
| Mac (Intel) | Pending in 2.3 | No | — (use 1.x wheel) |
Android (arm64-v8a) | Yes | No | Kotlin |
| Browser (WASM) | Yes | No | JavaScript / TS † |
| Linux x86_64 / aarch64 | Yes (CPU) | Yes (NVIDIA GPU) | Python, CLI |
| Windows | Pending (WSL2 today) | No | — |
| Raspberry Pi 4B / 5 | Near real-time | No | Python, CLI |
| bitHuman Cloud | Managed | Managed | LiveKit · JS / TS † |
All hosts that run a given model produce identical, lip-synced visual frames — your device choice is about form factor, memory, and latency budget, not visual quality. The detailed per-model hardware floors follow.
† The JavaScript / TypeScript client is Preview — not yet released (no npm package or public source yet; see the JavaScript / TypeScript section). For browser/Node today, drive a cloud avatar over LiveKit.
Essence
The default avatar model. Runs on virtually every supported platform — the right choice for mobile, edge, and any deployment without a discrete GPU.
| Host | Status | Notes |
|---|---|---|
| Apple M-series Mac | Real-time, large memory headroom | Any Apple Silicon (arm64) |
| iPhone 16 Pro+ | Real-time, smallest memory footprint | iOS 26 |
| iPad Pro M4+ | Real-time | Pairs comfortably with an on-device LLM |
Android (arm64-v8a) | Real-time | Snapdragon 8 Gen 2+, Android 10+ |
| Linux x86_64 / aarch64 | Real-time | Python SDK, modern CPU + 4 GB RAM |
| Intel Mac | Pending in 2.3 | Use 1.x wheel or run via Linux x86_64 |
| Windows x86_64 | Not shipping in 2.3 | Use WSL2 today; native wheels on the roadmap |
| Raspberry Pi 4B / 5 | Near real-time | Adequate for kiosks at modest FPS |
| Apple Watch / wearables | Not supported | Insufficient memory |
All hosts produce identical frames — your device decision is about form factor, memory, and latency budget, not visual quality.
Expression
Heavier high-fidelity model. Runs on Apple Silicon on-device (demo apps) or on NVIDIA GPUs server-side.
| Host | Status | Notes |
|---|---|---|
| Mac M3+ (arm64) | On-device | Demo app target |
| iPad Pro M4+ | On-device | Sized for 16 GB+ devices |
| iPhone 16 Pro+ | Preview | Needs the increased-memory entitlement; on-device validation in progress. Prefer Essence for production. |
| Android | Not supported | Use Essence. |
| Linux + NVIDIA GPU | Server | 8 GB+ VRAM via the self-hosted Docker container |
| Mac Intel / Linux CPU / Windows | Not supported | Requires Apple Silicon or NVIDIA GPU |
| Raspberry Pi | Not supported | Use Essence |
If you’re deploying to iPhone today, choose Essence. The iPhone reference app is built around Essence and stays well inside Apple’s per-app memory cap.
Avatar resolutions
Resolution interacts with both model and host:
| Resolution | Best for |
|---|---|
| 384×384 | Mobile and edge — the default sweet spot |
| 512×512 | Mac and iPad Pro — comfortable on M-series |
| 1280×720 | Desktop and cloud streaming — default for the CLI and LiveKit plugin |
Frames are delivered at 1280×720 by every SDK; smaller avatars are letterboxed / pillarboxed into that frame.
Engine ABI history
The engine ABI is the C surface libessence exposes to its language wrappers. New ABI versions are additive — old SDK builds that target an earlier ABI keep working against newer engines until a version is formally retired.
| ABI | Introduced | Notes |
|---|---|---|
| v7 | libessence 1.19.1 | Adds be_runtime_tick_compose_from_mel — composing a tick directly from a mel feed. Current production baseline; covers every shipping SDK above. Backwards-compatible with v6 callers. (be_set_default_audio_encoder is an additive, ABI-unchanged entry point — it did not bump the ABI.) |
| v6 | libessence 1.16.0 | Streaming push-audio / pull-frame API. |
| v5 and earlier | pre-1.16 | Retired in production builds — synchronous tick-compose only, no streaming. |
Confirm the ABI tag on a live host with bithuman doctor.