# ManiSkill 3：安装、运行 PickCube-v1 并保存观测视频

> 原文链接：https://robotics.hellobike.com/tutorials/maniskill3-install-first-task
> 频道：tutorials | 更新日期：2026-10-22 | 标签：ManiSkill 3, SAPIEN, Gymnasium, PickCube-v1, Vulkan, 机器人仿真
> 核心摘要：本教程按 ManiSkill 3.0.1 文档整理：完成 pip 安装，配置资产目录与 Vulkan 渲染依赖，运行 PickCube-v1 随机动作示例，并使用文档提供的命令保存视觉观测视频。

# ManiSkill 3：安装、运行 PickCube-v1 并保存观测视频

> 本文依据以下官方文档整理：[maniskill.readthedocs.io/en/latest/user_guide/getting_starte](https://maniskill.readthedocs.io/en/latest/user_guide/getting_started/installation.html)、[maniskill.readthedocs.io/en/latest/user_guide/getting_starte](https://maniskill.readthedocs.io/en/latest/user_guide/getting_started/quickstart.html)。命令与版本以文档当前版本为准。

## 前置条件

- Linux based systems；文档说明目前 best support Linux based systems
- NVIDIA GPU；Linux / NVIDIA GPU 支持 CPU Sim、GPU Sim 和 Rendering
- pip 安装环境
- 如需 rendering，需要 GPU with the Vulkan driver installed
- state-based simulation 不需要额外依赖

## 1. 安装 ManiSkill 3 与 torch

ManiSkill 的安装方式是运行少量 pip install。文档给出稳定版安装命令，并说明也提供 nightly version，每当 ManiSkill 有变化时每日更新。二选一执行即可。
```bash
## install the package and a version of torch that is compatible with your system
pip install --upgrade mani_skill torch
```
```bash
pip install mani_skill-nightly torch
```

## 2. 配置 ManiSkill 数据目录与资产下载提示

ManiSkill 有许多 assets、demonstration datasets 等不会默认下载。可以把 MS_ASSET_DIR 改到希望保存全部 ManiSkill 数据的位置；默认目录是 ~/.maniskill/data。也可跳过缺失资产时的下载提示。
```bash
export MS_ASSET_DIR=path/to/where/to/save/all/mani_skill_data
```
```bash
export MS_SKIP_ASSET_DOWNLOAD_PROMPT=1
```

## 3. 在 Ubuntu 上安装并测试 Vulkan

文档说明 state-based simulation 不需要额外依赖，但启用 ManiSkill rendering 需要安装 Vulkan driver。Ubuntu 上先安装 libvulkan1；再安装 vulkan-tools，并用 vulkaninfo 测试 Vulkan 信息是否能正常显示。
```bash
sudo apt-get install libvulkan1
```
```bash
sudo apt-get install vulkan-tools
vulkaninfo
```

## 4. 运行第一个刚体任务 PickCube-v1

安装后，powered by SAPIEN 的 rigid-body tasks 已可使用。用官方随机动作示例测试安装：默认运行 PickCube-v1 的一个 episode，最多 50 steps；也可以通过 -e ${ENV_ID} 指定任务。
```bash
## Run an episode (at most 50 steps) of "PickCube-v1" (a rigid-body task) with random actions
## Or specify an task by "-e ${ENV_ID}"
python -m mani_skill.examples.demo_random_action
```

## 5. 用命令行运行 PickCube-v1 并切换渲染方式

Quickstart 给出同一随机动作示例的命令行用法。headless 模式无需 display；如果使用 render_mode="human"，会打开 GUI，可交互探索场景、暂停或播放脚本、移动物体等。
```bash
## run headless / without a display
python -m mani_skill.examples.demo_random_action -e PickCube-v1
## run with A GUI and ray tracing
python -m mani_skill.examples.demo_random_action -e PickCube-v1 --render-mode="human" --shader="rt-fast"
```

## 6. 保存视觉观测视频

文档在 parallelized rendering 示例中提供了保存视频的命令：可渲染来自所有相机的 RGB + Depth 数据，也可以直接保存 64 个视觉观测视频，并放入一个视频中。
```bash
## rendering RGB + Depth data from all cameras
python -m mani_skill.examples.benchmarking.gpu_sim --num-envs=64 --obs-mode="rgbd"
## directly save 64 videos of the visual observations put into one video
python -m mani_skill.examples.benchmarking.gpu_sim --num-envs=64 --save-video
```

## 验证是否跑通

确认 pip 安装命令完成无报错；运行 python -m mani_skill.examples.demo_random_action 能执行 PickCube-v1 随机动作 episode；如需渲染，vulkaninfo 能显示 Vulkan 信息，render_mode="human" 可打开 GUI；运行 --save-video 命令可保存视觉观测视频。

## 文档里点名的注意事项

- GPU with the Vulkan driver installed is required to enable rendering in ManiSkill
- state-based simulation does not require any additional dependencies
- Changing num_envs to a value greater than 1 will automatically turn on the GPU simulation mode
- Running with render_mode="human" will open up a GUI；a display is required to render
- We currently best support Linux based systems；there is limited support for windows and no support for MacOS at the moment
- 如果 vulkaninfo fails to show the information about Vulkan，需要检查 /usr/share/vulkan/icd.d/nvidia_icd.json、/usr/share/glvnd/egl_vendor.d/10_nvidia.json、/etc/vulkan/implicit_layer.d/nvidia_layers.json

## 原始参考来源 (Sources)

- [maniskill.readthedocs.io/en/latest/user_guide/getting_started/installation.html](https://maniskill.readthedocs.io/en/latest/user_guide/getting_started/installation.html)
- [maniskill.readthedocs.io/en/latest/user_guide/getting_started/quickstart.html](https://maniskill.readthedocs.io/en/latest/user_guide/getting_started/quickstart.html)