Installation

Polyglot SDKs plus a standalone CLI. Most packages ship prebuilt binaries for Linux (x86_64/aarch64), macOS, and Windows — no compile step needed.

CLI / Docker

No SDK, no code — just your terminal.

Install script

curl -fsSL https://raw.githubusercontent.com/xberg-io/xberg/main/scripts/install.sh | bash

Homebrew

brew trust xberg-io/tap
brew install xberg-io/tap/xberg

Cargo

cargo install xberg-cli

Docker (CLI image)

docker pull ghcr.io/xberg-io/xberg-cli:latest
docker run -v $(pwd):/data ghcr.io/xberg-io/xberg-cli:latest extract /data/document.pdf

Docker (full image)

docker pull ghcr.io/xberg-io/xberg:latest

MCP Server included

Prebuilt binaries (Homebrew, install.sh, Docker full) include the MCP server. If building from source with cargo install xberg-cli, add --features mcp (or --features mcp-http for HTTP transport) to include it.

CLI Usage API Server Guide

x86_64 CPU — AVX/AVX2 instruction set required

The bundled ONNX Runtime binaries require AVX/AVX2 CPU instructions. CPUs without AVX support (e.g. Intel Atom, Celeron N5105/Jasper Lake, older pre-2011 processors) will crash with an invalid opcode trap when using ONNX-dependent features. The affected features are PaddleOCR, layout detection, embeddings, reranking, auto-rotate, and transcription. All other Xberg functionality (text extraction, Tesseract OCR, chunking, metadata, etc.) works normally on any x86_64 CPU. ARM platforms (aarch64) are unaffected.

Windows — ONNX Runtime required for Go, Elixir, and C/C++

Go, Elixir, and C/C++ bindings on Windows link against ONNX Runtime dynamically. You must have onnxruntime.dll on your PATH at runtime. Download it from the ONNX Runtime releases (for example onnxruntime-win-x64-1.24.1.zip). Python, TypeScript, Java, C#, Ruby, PHP, and Wasm are unaffected.

C# / .NET in a Linux container — publish with a RID and set LD_LIBRARY_PATH

The XbergIo.Xberg NuGet package ships its native library as a per-RID runtime package (XbergIo.Xberg.runtime.<rid>) resolved through a runtime.json graph, the same pattern as Microsoft.Data.Sqlite. Two container gotchas:

1. Publish with a runtime identifier so the natives deploy. Use dotnet publish -r linux-x64 (Aspire’s SDK container publish does this). The RID must be known at restore time — a RID-less dotnet restore followed by dotnet publish -r linux-x64 --no-restore won’t pull the runtime package (you’ll see NETSDK1047), and the ONNX Runtime closure never lands next to your app.
2. Point the dynamic loader at your app directory. The bundled libxberg_ffi.so loads libonnxruntime.so.1 beside it, but the container’s loader may not resolve it via the library’s RUNPATH, surfacing as DllNotFoundException on the first extraction. Set LD_LIBRARY_PATH to your app directory — ENV LD_LIBRARY_PATH=/app in a Dockerfile, or .WithEnvironment("LD_LIBRARY_PATH", "/app") in .NET Aspire (/app is the working directory in the standard .NET container images).

Intel Macs (x86_64) — prebuilt binaries are limited

Apple Silicon (arm64) macOS is fully supported across every package. On Intel Macs (x86_64), prebuilt binaries ship only for the CLI (install script, Homebrew, and the release tarball) and the Python wheel. The TypeScript/Node, Go, Java, Kotlin, C#, Dart, C/C++, Ruby, PHP, and Elixir packages ship macOS prebuilts for Apple Silicon only — on an Intel Mac they fall back to building the native library from source (a Rust toolchain is required). Intel-macOS is a legacy target: GitHub retires its last x86_64 macOS CI runner in 2027 and the bundled ONNX Runtime has no Intel-macOS build, so Intel support is best-effort and will be removed. Prefer Apple Silicon where you can.

Choose your language

• Python

---

pip install xberg

API Reference Quick Start

• TypeScript (Node.js / Bun)

---

npm install @xberg-io/xberg

API Reference Quick Start

• TypeScript (Browser / Edge)

---

npm install @xberg-io/xberg-wasm

API Reference Quick Start

• Rust

---

cargo add xberg

API Reference Quick Start

• Go

---

go get github.com/xberg-io/xberg/packages/go@latest

API Reference Quick Start

• Java

---

implementation 'io.xberg:xberg:1.0.0-rc.14'

API Reference Quick Start

• Kotlin Android

---

implementation("io.xberg:xberg-android:1.0.0-rc.14")

API Reference Quick Start

• Ruby

---

gem install xberg

API Reference Quick Start

• Swift

---

.package(url: "https://github.com/xberg-io/xberg.git", from: "1.0.0-rc.14")

API Reference Quick Start

• C# / .NET

---

dotnet add package XbergIo.Xberg

API Reference Quick Start

• PHP

---

composer require xberg-io/xberg

API Reference Quick Start

• Elixir

---

{:xberg, "~> 1.0.0-rc.14"}

API Reference Quick Start

• C / C++

---

cargo build -p xberg-ffi

API Reference Quick Start

• Dart / Flutter

---

dart pub add xberg

API Reference Quick Start

• Zig

---

zig fetch --save https://github.com/xberg-io/xberg/archive/refs/tags/v1.0.0-rc.14.tar.gz

API Reference Quick Start

---

System requirements

Only relevant if building from source or enabling OCR:

Dependency	When you need it
AVX/AVX2 CPU instructions	Required for ONNX Runtime features (PaddleOCR, layout detection, embeddings, reranking, auto-rotate, transcription) on x86_64
Rust toolchain (rustup)	Building any native binding from source
C/C++ compiler	Building native bindings (Xcode command-line tools / build-essential / MSVC)
Tesseract OCR	Optional — brew install tesseract / apt install tesseract-ocr
libheif (HEIC / HEIF / AVIF)	Optional — brew install libheif / apt install libheif-dev / dnf install libheif-devel

PDF extraction uses pdf_oxide and has no external PDF runtime dependency.

The Wasm package (@xberg-io/xberg-wasm) has zero system dependencies.

HEIF / HEIC / AVIF support

Pixel decoding for Apple HEIC photos, HEIF still images, AVIF, HEIC sequences (.heics), and AVCS requires the heic Cargo feature plus the system libheif library (with libde265 for HEVC and libaom for AV1):

• macOS: brew install libheif
• Debian / Ubuntu: apt install libheif-dev
• Fedora: dnf install libheif-devel
• Windows (vcpkg): vcpkg install libheif[hevc,aom]:x64-windows

Enable the feature when building from source:

xberg = { version = "1", features = ["heic", "ocr"] }

heic is included in the full aggregate feature. HEIC pixel decoding is not available on wasm-target or android-target (libheif is a C library with no working WASM/Android build story). EXIF metadata extraction from HEIC / HEIF / AVIF works on every target via the pure-Rust nom-exif integration.

GPU Acceleration

Xberg bundles a CPU-only ONNX Runtime — ML features (PaddleOCR, layout detection, embeddings, reranking, auto-rotate, transcription) work out of the box on CPU.

For GPU acceleration, install a GPU-enabled ONNX Runtime and set ORT_DYLIB_PATH:

Platform	Install	Set ORT_DYLIB_PATH
Linux (CUDA)	Download from ONNX Runtime releases	export ORT_DYLIB_PATH=/path/to/libonnxruntime.so
Python (any OS)	pip install onnxruntime-gpu	Point at the pip package’s capi/ directory
macOS (CoreML)	Works with bundled ORT — no extra setup needed	—

See AccelerationConfig and ORT_DYLIB_PATH for details.

---

Language-specific notes

Edge cases and alternative install methods where they come up.

TypeScript

Two npm packages target different runtimes:

Package	Best for	Performance
@xberg-io/xberg	Node.js, Bun — server-side apps	Native (100%)
@xberg-io/xberg-wasm	Browsers, Deno, Cloudflare Workers	Wasm (~60-80%)

Both work with pnpm (pnpm add) and Yarn (yarn add) as well.

pnpm workspaces

In monorepos, add this to your root .npmrc so platform-specific optional deps resolve correctly:

auto-install-peers=true

Wasm — Browser usage

<script type="module">
  import { ExtractInputKind, initWasm, extract } from "@xberg-io/xberg-wasm";

  await initWasm();

  const input = document.getElementById("file");
  input.addEventListener("change", async (e) => {
    const file = e.target.files?.[0];
    if (!file) return;

    const output = await extract({
      kind: ExtractInputKind.Bytes,
      bytes: new Uint8Array(await file.arrayBuffer()),
      mimeType: file.type || "application/octet-stream",
      filename: file.name,
    });
    console.log(output.results[0].content);
  });
</script>

<input type="file" id="file" />

Wasm — Deno

import { ExtractInputKind, initWasm, extract } from "npm:@xberg-io/xberg-wasm";

await initWasm();
const output = await extract({
  kind: ExtractInputKind.Uri,
  uri: "./document.pdf",
});
console.log(output.results[0].content);

Wasm — Cloudflare Workers

import { ExtractInputKind, initWasm, extract } from "@xberg-io/xberg-wasm";

export default {
  async fetch(request: Request): Promise<Response> {
    await initWasm();
    const bytes = new Uint8Array(await request.arrayBuffer());
    const output = await extract({
      kind: ExtractInputKind.Bytes,
      bytes,
      mimeType: "application/pdf",
    });
    return Response.json({ content: output.results[0]?.content ?? "" });
  },
};

Supported runtimes: Chrome 74+, Firefox 79+, Safari 14+, Edge 79+, Node.js 22+, Deno 1.35+, Cloudflare Workers.

Wasm — package layout (web target only)

@xberg-io/xberg-wasm publishes a single wasm-pack web target — a standard ES module you import directly in the browser, over a CDN (jsDelivr/unpkg), in Deno via npm:, in Cloudflare Workers, and in Node.js 22+ (ESM). Dedicated bundler, Node-CommonJS, and Deno target builds are not shipped: each is a full copy of the ~100MB wasm binary, and shipping all four pushed the npm package past jsDelivr’s 150MB per-package CDN limit (which broke the live demo’s CDN load). Modern bundlers (Vite, webpack 5, Rollup, esbuild) consume the web target directly. Initialize with await initWasm() (or the default init() export) before calling extract.

Wasm Platform Limitations

The Wasm binding does not support:

• PaddleOCR, embeddings, reranking, and transcription inference (all require ONNX Runtime)
• LLM/VLM features (liter-llm is not part of the wasm-target feature set)
• Hardware acceleration config (single-threaded WASM, no GPU access)
• Native server features (api, mcp, CLI binary)
• Tree-sitter code intelligence (the 371-language grammar pack exceeds the 50 MB CDN per-file cap)
• Browser filesystem paths (use kind = "bytes" for browser file uploads; path APIs require Node/Deno/Bun filesystem access)
• Email codepage config (EmailConfig not available)

Layout detection (RT-DETR) and document-orientation detection do run in Wasm through the pure-Rust tract engine (layout-tract + auto-rotate-tract): the detectLayout / detectOrientation exports take the .onnx weights as streamed bytes, which the JS host fetches and passes in. Pure-Rust extraction formats, OCR via Tesseract WASM, chunking, metadata, tables, language detection, SVG handling, redaction, summarization, QR-code detection, and image extraction also work in WASM. See the WASM API Reference for details.

Java

Maven

<dependency>
    <groupId>io.xberg</groupId>
    <artifactId>xberg</artifactId>
    <version>1.0.0-rc.14</version>
</dependency>

Gradle

implementation 'io.xberg:xberg:1.0.0-rc.14'

Requires Java 25+ (FFM/Panama API). Native libraries are bundled in the JAR.

Elixir

Add to mix.exs:

def deps do
  [
    {:xberg, "~> 1.0.0-rc.14"}
  ]
end

mix deps.get

Ships prebuilt NIF binaries via RustlerPrecompiled. Falls back to compiling from source if no prebuilt matches your platform (requires Rust).

Windows

The Windows NIF links against ONNX Runtime dynamically. onnxruntime.dll must be on your PATH at runtime — see the note at the top of this page.

Go

go get github.com/xberg-io/xberg/packages/go@latest

Not a Go module

The repository root is not a Go module — go get github.com/xberg-io/xberg (without the /packages/go suffix) fails, resolving against a stale Go module-proxy cache entry. Always target the /packages/go subdirectory as shown above.

Windows

The Go binding links against ONNX Runtime dynamically on Windows. onnxruntime.dll must be on your PATH at runtime — see the note at the top of this page.

Windows feature limitations

The Go and C/C++ bindings on Windows (MinGW/GNU target) do not include ORT-dependent inference features: PaddleOCR, layout detection, embeddings, reranking, auto-rotate, or transcription. Tesseract OCR and non-ORT features work normally. These limitations apply only to Windows; Linux and macOS builds include the full feature set.

Rust

Enable features selectively in Cargo.toml:

Cargo.toml

[dependencies]
xberg = { version = "1", features = ["pdf", "ocr", "chunking"] }
# Default features are tokio-runtime + simd-utf8; format and analysis features are opt-in.

C / C++

Build the FFI library from source:

cargo build --release -p xberg-ffi

This produces libxberg_ffi.a and a header at crates/xberg-ffi/xberg.h. Link into your project:

HEADER_DIR = path/to/crates/xberg-ffi
LIBDIR     = path/to/target/release

CFLAGS  = -Wall -Wextra -I$(HEADER_DIR)
LDFLAGS = -L$(LIBDIR) -lxberg_ffi -lpthread -ldl -lm

my_app: my_app.c
  $(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)

Platform-specific linker flags

macOS: add -framework CoreFoundation -framework Security

Windows: add -lws2_32 -luserenv -lbcrypt

Windows

The Windows FFI library links against ONNX Runtime dynamically. onnxruntime.dll must be on your PATH at runtime — see the note at the top of this page.

API Reference →

Dart / Flutter

Pure-Dart and Flutter consumers share the same package. Dart SDK 3.0 or higher is required. Flutter is supported on macOS, iOS, Android, Linux, and Windows; Flutter Web is not supported because the runtime is a native dynamic library delivered via flutter_rust_bridge. For Flutter projects use flutter pub add xberg instead of dart pub add xberg.

Kotlin

Kotlin/JVM consumers use the Java artifact (io.xberg:xberg) directly; Kotlin interoperates with the generated Java records and static facade.

Kotlin Android uses the Android AAR (io.xberg:xberg-android). It embeds JNI libraries for arm64-v8a and x86_64, targets Android API 21+, and uses the android-target feature set, which excludes most ORT-dependent inference features (PaddleOCR, layout detection, embeddings, reranking, transcription). Document-orientation detection runs through the pure-Rust tract engine (auto-rotate-tract) instead, so it is available on x86_64 as well as arm64-v8a.

Swift

Swift Package Manager from swift-tools-version: 6.0 upward. Package.swift declares macOS 13+ and iOS 16+; SwiftPM has no platform declaration for Linux, so no minimum is stated there. The package pulls a prebuilt static library through a binaryTarget (RustBridgeBinary), so consuming it needs no local cargo build.

Zig

Requires Zig 0.16.0 or higher (declared via minimum_zig_version in build.zig.zon). The Zig binding consumes the C FFI surface from xberg-ffi via linkSystemLibrary; the build expects the consumer to provide a search path to the prebuilt libxberg_ffi and the C header xberg.h. The zig fetch command above pins the source archive in build.zig.zon; wire it into build.zig via b.dependency("xberg", ...).

---

Development setup

For working on the Xberg repository itself:

task setup      # installs all language toolchains
task lint        # linters across all languages
task dev:test    # full test suite

See Contributing for conventions and expectations.