状态: 已弃用

mujoco-py 不支持 MuJoCo 2.1.0 之后的版本。

新用户应依赖 官方 MuJoCo Python 绑定。

mujoco-py

MuJoCo 是一个用于详细、高效的刚体接触模拟的物理引擎。 mujoco-py 允许从 Python 3 中使用 MuJoCo。

该库已更新，以兼容于 2021 年 10 月 18 日发布的 MuJoCo 2.1 版本。

概述

要求

目前支持以下平台：

• Linux，Python 3.6+。请参阅 Dockerfile 以获取标准的系统依赖列表。
• OS X，Python 3.6+。

以下平台已被弃用且不受支持：

• Windows 支持已在 2.0.2.0 中被弃用并移除。一个已知可用的旧版本是 1.50.1.68。
• Python 2 已在 1.50.1.0 中被弃用并移除。Python 2 用户可以继续使用 0.5 分支。该分支的最新版本是 0.5.7，可以通过 pip install mujoco-py==0.5.7 进行安装。

安装 MuJoCo

1. 下载 MuJoCo 2.1 的二进制文件，适用于 Linux 或 OSX。
2. 将下载的 mujoco210 目录解压到 ~/.mujoco/mujoco210。

如果您希望指定非标准的安装位置，请使用环境变量 MUJOCO_PY_MUJOCO_PATH。

安装和使用 mujoco-py

要将 mujoco-py 包含在您自己的项目中，请按如下方式将其添加到您的依赖项中：

mujoco-py<2.2,>=2.1

若想交互式地体验 mujoco-py，请按照以下步骤操作：

$ pip3 install -U 'mujoco-py<2.2,>=2.1'
$ python3
import mujoco_py
import os
mj_path = mujoco_py.utils.discover_mujoco()
xml_path = os.path.join(mj_path, 'model', 'humanoid.xml')
model = mujoco_py.load_model_from_path(xml_path)
sim = mujoco_py.MjSim(model)

print(sim.data.qpos)
# [0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0.]

sim.step()
print(sim.data.qpos)
# [-2.09531783e-19  2.72130735e-05  6.14480786e-22 -3.45474715e-06
#   7.42993721e-06 -1.40711141e-04 -3.04253586e-04 -2.07559344e-04
#   8.50646247e-05 -3.45474715e-06  7.42993721e-06 -1.40711141e-04
#  -3.04253586e-04 -2.07559344e-04 -8.50646247e-05  1.11317030e-04
#  -7.03465386e-05 -2.22862221e-05 -1.11317030e-04  7.03465386e-05
#  -2.22862221e-05]

有关高级用法，请参阅 完整文档。

故障排除

您使用的是 macOS，并遇到 clang: error: unsupported option '-fopenmp'

如果此错误发生在安装过程中或运行 python -c "import mujoco_py" 时，则问题可能与 此处相关。简而言之，macOS 默认使用的 Apple clang LLVM 编译器不支持 OpenMP。因此，您可以尝试安装其他版本的 clang/llvm。例如（需要 brew）：

brew install llvm
brew install boost
brew install hdf5

# 将以下内容添加到您的 .bashrc/.zshrc：
export PATH="/usr/local/opt/llvm/bin:$PATH"

export CC="/usr/local/opt/llvm/bin/clang"
export CXX="/usr/local/opt/llvm/bin/clang++"
export CXX11="/usr/local/opt/llvm/bin/clang++"
export CXX14="/usr/local/opt/llvm/bin/clang++"
export CXX17="/usr/local/opt/llvm/bin/clang++"
export CXX1X="/usr/local/opt/llvm/bin/clang++"

export LDFLAGS="-L/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"

注意: 编辑完 .bashrc/.zshrc 后，请务必重新加载它，并再次尝试安装 mujoco-py：

# 确保您的 Python 环境已激活
pip install -U 'mujoco-py<2.2,>=2.1'

缺少 GLFW

安装时常出现的错误之一是：

raise ImportError("Failed to load GLFW3 shared library.")

这通常是因为 glfw Python 包无法找到 GLFW 动态库。

MuJoCo 自带了一份该库的副本，可在安装时使用。

将 MuJoCo 二进制目录路径添加到动态链接器中：

LD_LIBRARY_PATH=$HOME/.mujoco/mujoco210/bin pip install mujoco-py

这在没有 GLFW 包的 Ubuntu 14.04 上尤其有用。

Ubuntu 安装故障排除

由于 mujoco_py 包含需要与提供的 MuJoCo 二进制文件链接的编译后原生代码，因此在 Linux 上的安装比纯 Python 源码包更为复杂。

要在 Ubuntu 上安装 mujoco-py，请确保已安装以下库：

sudo apt install libosmesa6-dev libgl1-mesa-glx libglfw3

如果您已安装上述库，但仍提示找不到 -lGL，很可能需要手动创建符号链接：

sudo ln -s /usr/lib/x86_64-linux-gnu/libGL.so.1 /usr/lib/x86_64-linux-gnu/libGL.so

使用示例

在 examples/ 中可以找到许多演示 mujoco-py 高级功能的示例。其中包括：

• body_interaction.py: 展示碰撞物体之间的相互作用
• disco_fetch.py: 展示如何使用 TextureModder 随机化对象纹理
• internal_functions.py: 展示如何调用原始 MuJoCo 函数，如 mjv_room2model
• markers_demo.py: 展示如何向查看器添加仅用于可视化的几何体
• serialize_model.py: 展示如何保存和恢复模型
• setting_state.py: 展示如何将模拟重置为给定状态
• tosser.py: 展示一个简单的驱动型物体分拣机器人应用

有关高级用法，请参阅 完整文档。

开发

要运行提供的单元测试和集成测试：

make test

要测试 GPU 加速渲染，请运行：

make test_gpu

目前这在一定程度上依赖于 OpenAI 内部基础设施，但如果您根据自己的设置调整 Makefile 参数，应该也能正常运行。

更改记录

• 2018年8月3日：我们移除了 MjSimPool，因为多个进程共享单个模拟所带来的好处并不多。

致谢

mujoco-py 由 OpenAI 机器人团队维护。贡献者包括：

• Alex Ray
• Bob McGrew
• Jonas Schneider
• Jonathan Ho
• Peter Welinder
• Wojciech Zaremba
• Jerry Tworek

mujoco-py 快速上手指南

⚠️ 重要提示：mujoco-py 目前已停止维护 (Deprecated)，仅支持 MuJoCo 2.1.0 及以下版本。 新用户强烈建议直接使用 官方 MuJoCo Python bindings。本指南仅供需要兼容旧项目或特定 2.1.0 版本的开发者参考。

1. 环境准备

系统要求

• 操作系统：Linux 或 macOS (Windows 支持已移除)
• Python 版本：Python 3.6+

前置依赖

在安装前，请确保系统已安装以下基础库：

Ubuntu/Debian:

sudo apt update
sudo apt install libosmesa6-dev libgl1-mesa-glx libglfw3 patchelf

macOS: 需使用 Homebrew 安装 LLVM 以解决 OpenMP 编译问题：

brew install llvm boost hdf5

注：macOS 用户需在 .bashrc 或 .zshrc 中配置 LLVM 路径（见下文安装步骤中的环境变量部分）。

2. 安装步骤

第一步：下载并配置 MuJoCo 2.1.0

mujoco-py 强依赖本地安装的 MuJoCo 二进制文件。

1. 下载 MuJoCo 2.1.0：

   • Linux 版
   • macOS 版

2. 解压到默认目录 ~/.mujoco/mujoco210：

mkdir -p ~/.mujoco
cd ~/.mujoco
# 将下载的 tar.gz 文件替换为实际文件名
tar -xzf mujoco210-linux-x86_64.tar.gz 
# 确保解压后的文件夹名为 mujoco210

3. (可选) 如果安装在非默认路径，设置环境变量：

export MUJOCO_PY_MUJOCO_PATH=/your/custom/path/mujoco210

第二步：配置环境变量 (macOS 用户必读)

macOS 用户必须指定使用 LLVM 编译器，否则会出现 unsupported option '-fopenmp' 错误。

将以下内容添加到 ~/.bashrc 或 ~/.zshrc：

export PATH="/usr/local/opt/llvm/bin:$PATH"
export CC="/usr/local/opt/llvm/bin/clang"
export CXX="/usr/local/opt/llvm/bin/clang++"
export LDFLAGS="-L/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"

执行 source ~/.bashrc (或 source ~/.zshrc) 使配置生效。

第三步：安装 mujoco-py

建议使用国内镜像源加速安装（如清华源）：

pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple 'mujoco-py<2.2,>=2.1'

注：如果在 Linux 上安装时提示找不到 GLFW 库，请在安装命令前加上 LD_LIBRARY_PATH：

LD_LIBRARY_PATH=$HOME/.mujoco/mujoco210/bin pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple 'mujoco-py<2.2,>=2.1'

3. 基本使用

以下是最小化的代码示例，用于加载模型并运行一步仿真：

import mujoco_py
import os

# 自动发现 MuJoCo 安装路径
mj_path = mujoco_py.utils.discover_mujoco()

# 加载内置的人形机器人模型
xml_path = os.path.join(mj_path, 'model', 'humanoid.xml')
model = mujoco_py.load_model_from_path(xml_path)

# 创建仿真对象
sim = mujoco_py.MjSim(model)

# 打印初始位置状态
print("Initial qpos:", sim.data.qpos)

# 执行一步物理仿真
sim.step()

# 打印仿真后的位置状态
print("After step qpos:", sim.data.qpos)

如需更多高级功能（如渲染、状态重置、模型序列化），请参考项目 examples/ 目录下的官方示例代码。