mjlab

mjlab 结合了 Isaac Lab 的基于管理器（manager-based）API 与 MuJoCo Warp，后者是 MuJoCo 的 GPU 加速版本。 该框架为环境设计提供了可组合的构建模块， 依赖极少，并可直接访问原生的 MuJoCo 数据结构。

入门指南

mjlab 需要 NVIDIA GPU 进行训练。macOS 仅支持评估用途。

立即尝试：

运行演示（无需安装）：

uvx --from mjlab --refresh demo

或者在 Google Colab 中尝试（无需本地设置）。

从源码安装：

git clone https://github.com/mujocolab/mjlab.git && cd mjlab
uv run demo

对于其他安装方法（PyPI、Docker），请参阅 安装指南。

训练示例

1. 速度跟踪

训练 Unitree G1 人形机器人在平坦地形上跟随速度指令：

uv run train Mjlab-Velocity-Flat-Unitree-G1 --env.scene.num-envs 4096

多 GPU 训练： 使用 --gpu-ids 扩展至多个 GPU：

uv run train Mjlab-Velocity-Flat-Unitree-G1 \
  --gpu-ids "[0, 1]" \
  --env.scene.num-envs 4096

详见 分布式训练指南。

训练时评估策略（从 Weights & Biases 获取最新检查点）：

uv run play Mjlab-Velocity-Flat-Unitree-G1 --wandb-run-path your-org/mjlab/run-id

2. 运动模仿

训练人形机器人模仿参考动作。详见 运动模仿指南 以了解预处理设置。

uv run train Mjlab-Tracking-Flat-Unitree-G1 --registry-name your-org/motions/motion-name --env.scene.num-envs 4096
uv run play Mjlab-Tracking-Flat-Unitree-G1 --wandb-run-path your-org/mjlab/run-id

3. 使用虚拟代理进行健全性检查

在训练前使用内置代理对您的 MDP（马尔可夫决策过程）进行健全性检查：

uv run play Mjlab-Your-Task-Id --agent zero  # 发送零动作
uv run play Mjlab-Your-Task-Id --agent random  # 发送均匀随机动作

运行运动跟踪任务时，请在命令中添加 --registry-name your-org/motions/motion-name。

文档

完整文档可在 mujocolab.github.io/mjlab 获取。

开发

make test          # 运行所有测试
make test-fast     # 跳过慢速测试
make format        # 格式化与代码检查
make docs          # 本地构建文档

开发环境设置：uvx pre-commit install

引用

mjlab 被用于已发表的研究和开源机器人项目中。请查看 研究 页面以获取出版物和项目，或在 Show and Tell 中分享您自己的项目。

如果您在研究中使用了 mjlab，请考虑引用：

@misc{zakka2026mjlablightweightframeworkgpuaccelerated,
  title={mjlab: A Lightweight Framework for GPU-Accelerated Robot Learning},
  author={Kevin Zakka and Qiayuan Liao and Brent Yi and Louis Le Lay and Koushil Sreenath and Pieter Abbeel},
  year={2026},
  eprint={2601.22074},
  archivePrefix={arXiv},
  primaryClass={cs.RO},
  url={https://arxiv.org/abs/2601.22074},
}

许可

mjlab 采用 Apache License, Version 2.0 许可。

第三方代码

mjlab 的部分部分是从外部项目分叉而来的：

• src/mjlab/utils/lab_api/ — 从 NVIDIA Isaac Lab 分叉的工具（BSD-3-Clause 许可，见文件 头部）

分叉组件保留其原始许可。详情请参见文件头部。

致谢

如果没有 Isaac Lab 团队的杰出工作，mjlab 就不会存在，mjlab 正是建立在其 API 设计和抽象之上。

感谢 MuJoCo Warp 团队 —— 特别是 Erik Frey 和 Taylor Howell —— 回答我们的问题，提供有益反馈，并根据我们的请求无数次实现功能。

mjlab 快速上手指南

mjlab 是一个轻量级框架，结合了 Isaac Lab 的基于管理器的 API 与 MuJoCo Warp（GPU 加速版 MuJoCo）。它专为机器人学习设计，提供可组合的环境构建模块，支持直接访问原生 MuJoCo 数据结构。

环境准备

• 操作系统：推荐使用 Linux 进行训练；macOS 仅支持评估任务。
• 硬件要求：必须配备 NVIDIA GPU 用于训练。
• 前置依赖：
  • Python 环境
  • uv（高性能 Python 包管理器）
  • Git

注意：确保您的 NVIDIA 驱动已正确安装并支持 CUDA。

安装步骤

方法一：免安装体验（推荐新手）

无需本地配置，直接使用 uvx 运行演示：

uvx --from mjlab --refresh demo

或者在 Google Colab 中尝试（无需本地设置）。

方法二：从源码安装

克隆仓库并使用 uv 运行：

git clone https://github.com/mujocolab/mjlab.git && cd mjlab
uv run demo

如需其他安装方式（如 PyPI、Docker），请查阅官方 安装指南。

基本使用

1. 运行演示

进入项目目录后，运行以下命令启动基础演示：

uv run demo

2. 训练示例（速度跟踪）

训练 Unitree G1 人形机器人在平坦地形上跟随速度指令：

uv run train Mjlab-Velocity-Flat-Unitree-G1 --env.scene.num-envs 4096

多 GPU 训练：通过 --gpu-ids 参数扩展至多卡：

uv run train Mjlab-Velocity-Flat-Unitree-G1 \
  --gpu-ids "[0, 1]" \
  --env.scene.num-envs 4096

3. 策略评估

在训练过程中或之后评估策略（需指定 Weights & Biases 路径）：

uv run play Mjlab-Velocity-Flat-Unitree-G1 --wandb-run-path your-org/mjlab/run-id

4. 调试检查

使用内置代理进行 MDP 合理性检查：

# 发送零动作
uv run play Mjlab-Your-Task-Id --agent zero 

# 发送均匀随机动作
uv run play Mjlab-Your-Task-Id --agent random

提示：对于运动跟踪任务，请在命令中添加 --registry-name your-org/motions/motion-name。

---

更多详细文档请访问：mujocolab.github.io/mjlab