Rerun

How does Rerun work?

Rerun has several components manage multimodal data across its lifetime. This page explains what they are and how they connect.

The components the-components

Logging SDK logging-sdk

The Logging SDK is how you get data into Rerun. Available for Python, Rust, and C++, it runs inside your application and logs data using archetypes—structured types like Points3D, Image, or Transform3D.

Data can be streamed directly to the Viewer, saved to .rrd files, or both.

Viewer viewer

The Viewer visualizes your data. It comes in two forms:

  • Native Viewer: A desktop application for Linux, macOS, and Windows
  • Web Viewer: A browser based application

The viewer includes a Chunk Store (in-memory database for logged data) and a gRPC endpoint that accepts streamed data from the SDK.

The Web Viewer has performance limitations compared to the native viewer. It runs as 32-bit Wasm and is limited to ~2 GiB memory in practice, limiting the amount of data that can be visualized simultaneously. It also runs single-threaded, making it generally slower than native.

Both viewers can be extended: the Native Viewer through its Rust API, and the Web Viewer can be embedded in web applications or Jupyter notebooks.

Data platform data-platform

The Data Platform provides persistent storage and indexing for large-scale data. It organizes data into:

  • Datasets: Named collections of related recordings
  • Segments: Individual .rrd files registered to a dataset

Data is served via the redap protocol (Rerun Data Protocol).

The Data Platform is available as:

  • Open-source server for local development (rerun server)
  • Managed offering for production deployments

Catalog SDK catalog-sdk

The Catalog SDK (rerun.catalog) is a Python library for querying and manipulating the data stored on the Data Platform. Combined with the managed Data Platform, it allows building complex data transformation pipelines.

How they connect how-they-connect

Logging SDK.rrd filesViewerData PlatformCatalog SDKgRPC endpointChunk StoreRendererDatasets streamsaveloadregisterredapredap

What ships where? what-ships-where

Hosted web viewer hosted-web-viewer

The Web Viewer is available at rerun.io/viewer. It's a great place to start exploring the examples.

CLI cli

The rerun binary bundles multiple tools in one:

  • Native Viewer for visualization
  • OSS Data Platform server (via rerun server)
  • RRD tools for file manipulation
  • Web Viewer (via rerun --serve-web)

The Rerun CLI can be downloaded from GitHub or as part of the Python SDK. It can also be built from source with cargo install rerun-cli --locked.

See: CLI reference

Python SDK python-sdk

The Python SDK includes:

  • Logging SDK
  • Catalog SDK
  • CLI, including the Viewer (the rerun CLI is made available by installing the rerun-sdk Python package)

See: Python SDK installation instructions and quick start guide

Rust SDK rust-sdk

The Logging SDK as a Rust crate.

See: Rust SDK installation instructions and quick start guide

C++ SDK c-sdk

The Logging SDK for C++ projects.

See: C++ SDK installation instructions and quick start guide

The web-viewer and web-viewer-react NPM packages the-webviewer-and-webviewerreact-npm-packages

These NPM packages bundle the Web Viewer for inclusion on a website.

See: the web-viewer package reference

Common workflows common-workflows

Stream to Viewer stream-to-viewer

The simplest workflow: stream data directly from your code to the Viewer for live visualization.

Logging SDKViewer stream

Minimal example:

import rerun as rr

rr.init("rerun_example_log_to_grpc")

# Connect to the Rerun gRPC server using the default address and url: rerun+http://localhost:9876/proxy
rr.connect_grpc()

# Log data as usual, thereby pushing it into the gRPC connection.
while True:
    rr.log("/", rr.TextLog("Logging things…"))

Best for: development, debugging, real-time monitoring.

Save to RRD, view later save-to-rrd-view-later

Log data to .rrd files, then open them in the Viewer whenever needed. Files can be loaded from disk or URLs.

Logging SDK.rrdViewer saveload

Minimal example:

import rerun as rr

rr.init("rerun_example_log_to_rrd")

# Open a local file handle to stream the data into.
rr.save("/tmp/my_recording.rrd")

# Log data as usual, thereby writing it into the file.
while True:
    rr.log("/", rr.TextLog("Logging things…"))

And later:

$ rerun /tmp/my_recording.rrd

Best for: sharing recordings, offline analysis, archiving.

Store on data platform store-on-data-platform

Register .rrd files with the Data Platform for persistent, indexed storage. Query and visualize on demand.

.rrdData PlatformViewerCatalog SDK registerredapredap

Minimal example of creating a dataset and registering files:

import rerun as rr

client = rr.catalog.CatalogClient("rerun://example.cloud.rerun.io")
dataset = client.create_dataset("my_data")
dataset.register(["s3://my-rrd-files/recording1.rrd", "s3://my-rrd-files/recording2.rrd"])

Best for: large datasets, team collaboration, production pipelines.

Query and transform data query-and-transform-data

Use the Catalog SDK to query data from the Data Platform, process it, and write results back. Visualization is available at any time.

Data PlatformCatalog SDKViewer redap redapredap

Minimal example of querying a dataset:

import datafusion as dfn
import rerun as rr

client = rr.catalog.CatalogClient("rerun://example.cloud.rerun.io")
dataset = client.get_dataset("my_data")
df = dataset.filter_contents("/obs").reader(index="log_time")    # `df` is a DataFusion dataframe
df.filter(dfn.col("obs:Scalars:scalars").is_not_null()).count()  # count observations in recording

Best for: data pipelines, batch processing, ML training data preparation.

Privacy policy