Rerun 安装完全指南：Python / Rust / C++ SDK 与独立 Viewer 的一站式安装手册
项目地址: https://gitcode.com/GitHub_Trending/re/rerun Rerun 是一套面向多模态机器人数据（图像、点云、变换、时间序列、关节状态、视频等）的可视化与数据处理工具链，提供 Python、Rust、C++ 三种语言 SDK，以及功能完备的独立 Viewer。本文以仓库官方安装文档 docs/content/getting-started/install-rerun.md 为主体，完整覆盖三种 SDK 的安装方式、独立 Viewer 的全部安装途径，以及从 Linux 系统依赖、WSL2 图形环境、pip 版本问题到 wgpu 渲染后端、多 GPU 与视频解码卡顿的完整故障排查手册，并辅以仓库源码佐证，帮助你一步到位完成环境搭建。
安装方式总览：按你的语言选择入口
官方安装指南是一个"导航枢纽"：它不重复罗列细节，而是按语言将安装文档拆分为四份子文档，你只需要做一次选择：
| 你的技术栈 | 主安装文档 | 附带内容 |
|---|---|---|
| Python | Python SDK 安装 | SDK 与 Viewer 一次装齐 |
| Rust | Rust SDK 安装 | 仅 SDK，需另行安装 Viewer |
| C++ | C++ SDK 安装 | 仅 SDK，需另行安装 Viewer |
| 仅需可视化（任意语言） | Viewer 安装 | 独立 Viewer，安装方式最丰富 |
如果你在安装过程中遇到任何问题，可以直接查阅 Troubleshooting 指南，下文"故障排查"一节完整继承了该文档的全部内容。
方式一：Python SDK——一条命令同时拿到 SDK 和 Viewer
Python SDK 是上手最快的路径：它同时包含 SDK 与 Viewer，一次安装即可开始记录和可视化数据（这一设计也体现在仓库中 rerun_py 会打包 rerun-cli 二进制到 wheel 中）。
pip 安装（基础版）
pip install rerun-sdk
Conda 安装
conda install -c conda-forge rerun-sdk
Conda 渠道的包始终自带全部功能支持；而使用 pip 时，部分功能以"可选特性"（extras）的形式按需安装：
# 嵌入式 Notebook 工具（在 Jupyter 中嵌入 Rerun Viewer）
pip install rerun-sdk[notebook]
# 查询 API 工具（Rerun Catalog 查询能力）
pip install rerun-sdk[catalog]
# 模型训练工具（PyTorch Dataset 数据加载器）
pip install rerun-sdk[dataloader]
从源码可以确认这些 extras 的真实依赖：在 rerun_py/pyproject.toml 的 [project.optional-dependencies] 中，notebook 对应 rerun-notebook 包；catalog 依赖 datafusion 与 pandas（用于数据帧查询与纳秒时间戳转换）；dataloader 则声明了 torch>=2.5、torchvision、av（PyAV）与 pillow>=8.0.0，用于将 Rerun 数据直接以 PyTorch Dataset 形式喂给训练流程——这与项目"stream to train on multimodal robotics data"的定位一致。
快速验证安装
安装完成后，在任意 Python 文件中即可导入：
import rerun as rr
更完整的 Hello World（摘自 README.md）：
import rerun as rr # pip install rerun-sdk
rr.init("rerun_example_app")
rr.spawn() # 启动一个 Viewer 子进程并连接
# rr.save("recording.rrd") # 将所有日志流写入磁盘
# rr.connect_grpc() # 连接远程 Viewer
rr.set_time("frame", sequence=42)
rr.log("path/to/points", rr.Points3D(positions, colors=colors))
rr.init 使用稳定的 ApplicationId 命名本次记录，Viewer 会据此在多次运行间保留 UI 状态；关于 Recording 与 ApplicationId 的语义可参考 Recordings 概念文档。
下一步
安装完成后，按照 Python 项目配置 搭建项目骨架，然后进入 Log and Ingest 数据摄入教程 开始记录第一批数据。
方式二：Rust SDK——cargo 一条命令接入
Rust SDK 使用 Cargo 管理依赖，安装非常轻量：
cargo add rerun
这条命令会将 rerun crate 添加为项目的依赖（对应仓库中的 crates/top/rerun 目录）。
需要注意：Rust SDK 不附带 Viewer，你需要额外安装 Viewer，安装方法见下一节。
Rust 工具链版本要求
如果选择从源码构建 Viewer（cargo install rerun-cli --locked），需要 Rust 1.96 及以上。仓库根目录的 rust-toolchain 文件确认了当前开发基线：channel = "1.96.0"，并包含 rustfmt、clippy 组件与 wasm32-unknown-unknown 目标。
可选：在应用内直接嵌入 Viewer
Rust SDK 还支持通过 rerun::native_viewer::show 在进程内直接托管 Viewer（需要在 Cargo.toml 中启用 native_viewer feature），适用于从内存数据直接展示完整录制的场景，详见 Log and Ingest 教程 中的"Rust-only: showing the Viewer in-process"一节。
下一步
按照 Rust 项目配置 创建项目（cargo new + cargo add rerun），然后进入 Log and Ingest 教程。
方式三：C++ SDK——CMake FetchContent 集成
C++ SDK 通过 CMake 的 FetchContent 模块集成到现有构建系统中，官方推荐写法如下（完整继承自 C++ SDK 安装文档）：
include(FetchContent)
FetchContent_Declare(rerun_sdk URL
https://github.com/rerun-io/rerun/releases/latest/download/rerun_cpp_sdk.zip)
FetchContent_MakeAvailable(rerun_sdk)
构建配置的更多细节（如 Arrow C++ 库的下载与构建策略）见 C++ 参考文档中的 "Build & Distribution" 章节。
与 Rust 一样，C++ SDK 不附带 Viewer，需另行安装 Viewer。
版本与标准要求
- Rerun 要求 C++17 或更高，链接 SDK 会自动确保启用 C++17+；
- 更完整的项目模板（含
target_link_libraries(example_project PRIVATE rerun_sdk)与#include <rerun.hpp>）见 C++ 项目配置； - 从源码层面看，仓库的 rerun_cpp/CMakeLists.txt 通过
target_compile_features(rerun_sdk PUBLIC cxx_std_17)强制了 C++17 标准，并在 MSVC 下开启/MP多线程编译；SDK 头文件位于 rerun_cpp/src/rerun.hpp。
下一步
按照 C++ 项目配置 搭建 CMake 工程，然后进入 Log and Ingest 教程。
安装独立 Viewer：七种途径任选
Viewer 可以独立于任何语言 SDK 安装，适用于只想打开 .rrd / .mcap 等文件做可视化的场景。官方文档给出了多种安装途径，按你的环境任选其一：
| 途径 | 命令 / 方式 | 说明 |
|---|---|---|
| 预编译二进制 | 从官方 Release 产物下载 rerun-cli | 按平台选择对应压缩包，开箱即用 |
| Cargo 下载二进制 | cargo binstall rerun-cli | 通过 cargo-binstall 直接下载预编译产物，无需编译 |
| Cargo 源码编译 | cargo install rerun-cli --locked | 从源码构建，要求 Rust 1.96+ |
| Snap（社区维护） | snap install rerun | 从 Snap Store 安装 |
| 随 Python SDK 附带 | pip3 install rerun-sdk | 安装 Python SDK 即获得 rerun 命令 |
| 随 Python SDK 附带 | conda install -c conda-forge rerun-sdk | Conda 渠道同样附带 Viewer |
| 随 Python SDK 附带 | pixi global install rerun-sdk | 通过 Pixi 全局安装 |
安装完成后，运行 rerun 即可启动 Viewer，首屏是概览页，可以直接跳转进入示例。
版本匹配提醒
请确保库（SDK）版本与 Viewer 版本一致：Rerun 的数据格式在不同版本间尚未稳定（官方 issue 中明确记录了这一限制），混用版本可能导致无法正确打开录制数据。
rerun-cli 的组成与内置能力
从 crates/top/rerun-cli/Cargo.toml 可以看清 rerun 二进制的功能构成：
- 默认特性为
web_viewer+base，其中base包含native_viewer（原生 Viewer）、map_view（地图视图）、oss_server（进程内 Rerun Server）、perf_telemetry（OpenTelemetry 遥测）； - 预发布产物（
release_full）额外启用lance（Lance 表支持）与nasm（汇编优化的视频解码）； --locked参数保证按Cargo.lock锁定版本依赖树，构建结果可复现。
此外，Viewer 内置了对 RRD、MCAP、图片、视频、点云等多种文件格式的支持——这一点可以从 re_viewer/Cargo.toml 得到佐证：Viewer 显式依赖 re_importer 并启用 features = ["all"]，即打包了仓库中全部导入器（importer）。如果你需要打开 Rerun 尚未支持的文件类型，可以按 打开任意文件 所述扩展导入能力，无需修改 Rerun 本体。
故障排查：从 Linux 依赖到渲染后端的完整清单
本节完整继承 Troubleshooting 指南，并补充源码级的说明。
开启调试日志
在运行前设置环境变量，可获得更详细的日志输出：
RUST_LOG=debug rerun
Linux 系统依赖（Debian / Ubuntu 系）
Rerun 在 macOS 与 Windows 上开箱即用，但 Linux 需要先安装系统依赖：
sudo apt-get -y install \
libclang-dev \
libatk-bridge2.0 \
libfontconfig1-dev \
libfreetype6-dev \
libglib2.0-dev \
libgtk-3-dev \
libssl-dev \
libxcb-render0-dev \
libxcb-shape0-dev \
libxcb-xfixes0-dev \
libxkbcommon-dev \
patchelf
Fedora Rawhide 系统依赖
sudo dnf install \
clang \
clang-devel \
clang-tools-extra \
libxcb-devel \
libxkbcommon-devel \
openssl-devel \
pkg-config
Wayland 窗口管理器兼容问题
在 Wayland 窗口管理器下运行 Rerun 有时会导致崩溃（官方 issue 跟踪中），可尝试以下变通方案：
unset WAYLAND_DISPLAY # 或 WAYLAND_DISPLAY=
Ubuntu 24 上也观察到 Wayland 相关问题，可额外安装兼容库并同样取消 Wayland display：
sudo apt install libxkbcommon-x11-0
WSL2（Ubuntu）图形环境
WSL 自带的图形驱动无法开箱即用，需要更新到较新版本。安装最新稳定版 Mesa Vulkan 驱动：
sudo add-apt-repository ppa:kisak/kisak-mesa
sudo apt-get update
sudo apt-get install -y mesa-vulkan-drivers
由于 WSL 上的 Mesa 驱动会转发到 Windows 宿主机的图形驱动，务必保持 Windows 驱动为最新：例如已观察到 Windows 侧 AMD 驱动过旧时，在 WSL 中运行会出现线条渲染问题（官方 issue 记录）。
pip 安装失败：找不到 rerun-sdk
如果执行 pip install rerun-sdk 或 pip install rerun-notebook 时报错：
ERROR: Could not find a version that satisfies the requirement rerun-sdk (from versions: none)
ERROR: No matching distribution found for rerun-sdk
这通常意味着pip 版本过旧。先用 pip --version 检查版本，若为 pip 20 或更早，升级即可：
pip install --upgrade pip
[!WARNING] 视系统配置而定，升级命令可能升级的是
pip3别名对应的 pip 安装，而非pip对应的那个。
启动问题：重置 Viewer 内存
如果 Rerun 启动异常，可尝试重置其持久化内存：
rerun reset
图形问题：渲染后端与驱动
首先确保图形驱动保持最新。Rerun 的图形渲染基于 Wgpu（re_viewer 依赖 eframe 的 wgpu 特性，见 re_viewer/Cargo.toml），Wgpu 维护了一份已知驱动问题与规避方案清单。
Wgpu 的配置可通过以下方式干预：
--renderer=<backend>启动参数：<backend>必须是vulkan、metal或gl（原生 Viewer），或webgl、webgpu（Web Viewer，配合--web-viewer参数）。默认后端在除 macOS 外均为vulkan，macOS 使用metal；Web 端优先 WebGPU，检测不到时自动回退 WebGL。- 例如：
rerun --renderer=gl，Web Viewer 则为rerun --web-viewer --renderer=webgl； - 原生 Viewer 也可用环境变量
WGPU_BACKEND指定同样的取值； - Web Viewer 通过 URL 参数
renderer=<backend>配置。
- 例如：
WGPU_POWER_PREF：覆盖图形适配器选择的功耗偏好，取值必须为high或low，默认high。
这些设置在源码中有直接对应：rerun 二进制的 wgpu 配置由 crates/top/re_viewer/src/lib.rs 的 wgpu_options 与 customize_eframe_and_setup_renderer 负责组装，其中 instance_descriptor 依据 force_wgpu_backend 决定可用的后端集合；Web 端则在 crates/top/re_viewer/src/web.rs 的 AppOptions 中通过 render_backend、video_decoder 等字段接收 URL 参数（该结构需与 rerun_js/web-viewer/index.ts 的接口保持同步）。
[!NOTE] 官方建议仅在被告知尝试或明确知道自己在做什么时才修改这些设置，因为并非所有配置都得到同等程度的支持。
多 GPU 环境：强制指定显卡
在使用 Wgpu 的 Vulkan 后端（Windows 与 Linux 默认）且机器同时具有集显与独显时，Vulkan 可能运行时选错 GPU，或与其他驱动选择技术（如 NVIDIA Optimus）冲突，导致崩溃、渲染 artifacts 或性能下降。
可尝试用 VK_ICD_FILENAMES 环境变量强制 Vulkan 选择集显或独显（两种都可以试试）：
# 强制 Intel 集显（Linux）
export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/intel.json
# 强制 NVIDIA 独显（Linux）
export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia.json
# 强制 NVIDIA 独显（Windows）
set VK_ICD_FILENAMES=\windows\system32\nv-vk64.json
视频卡顿：强制软件解码
部分浏览器默认的视频解码器可能导致卡顿（例如 Windows 上的 Chrome 129 曾出现此问题）。可以通过 Viewer 的选项菜单配置软件解码，也可以在启动时覆盖：
- Web Viewer：URL 参数加
&video_decoder=prefer_software； - 原生 Viewer（以及通过命令行
--web-viewer启动的 Web Viewer）：传--video-decoder=prefer_software。
关于 Rerun 的视频解码与编码方式（Image、EncodedImage、AssetVideo、VideoStream 等不同选择在画质与体积之间的权衡），可参考 视频解码概念文档。
安装之后：下一步怎么走
环境就绪后，官方推荐的路径是：
- 搭建项目：Python 无需额外配置即可
import rerun as rr；Rust 执行cargo new+cargo add rerun；C++ 编写最小CMakeLists.txt。对应文档见 Python 项目配置、Rust 项目配置、C++ 项目配置； - 记录第一批数据：跟随 Log and Ingest 教程，用几十行代码完成从点云、线段到带时间轴的动画场景；该教程还覆盖了通过 gRPC 联网传输数据（Viewer 默认监听
0.0.0.0:9876，SDK 侧用connect_grpc连接）、通过save将数据流写入.rrd文件，以及 Rust 进程内嵌 Viewer 等进阶用法； - 直接打开已有文件：Viewer 可打开 RRD、MCAP、图片、视频、点云等格式，详见 打开任意文件；
- 熟悉界面：首次启动后可通过 Viewer 总览 了解 Blueprint、Selection、Timeline、Viewport 四大面板与命令面板（
Ctrl/Cmd + P）的使用方式。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
