📚 课程目录第4章 Python绑定安装

4、Python绑定安装：mujoco-py库的安装，常见安装错误及解决方案

好，到了这一步，我们终于要跟 Python 打交道了。MuJoCo 本身是 C/C++ 写的，但咱们做机器人仿真，绝大多数时候还是用 Python 来调。所以需要一个桥梁——mujoco-py。

这个库的安装，说简单也简单，说坑也确实不少。我最早在 Windows 上折腾的时候，光编译就卡了两天。后来换了 Linux，以为能省心，结果又遇到 GCC 版本不对。嗯，今天我把这些坑都给你捋一遍。

核心原则：mujoco-py 本质上是在你的系统上编译一个 Cython 扩展。所以，你的系统必须有一个能用的 C/C++ 编译器，以及 CMake 构建工具。

4.1 安装前的准备：编译器与构建工具

不管你用什么操作系统，先把编译器搞定。这是最容易被忽略的一步。

操作系统	所需工具	验证命令
Windows	Visual Studio Build Tools (MSVC)	`cl.exe` (在开发者命令提示符中)
Linux (Ubuntu/Debian)	GCC, G++, CMake, make	`gcc --version`, `cmake --version`
macOS	Xcode Command Line Tools (clang)	`clang --version`

4.1.1 Windows 用户：Visual Studio Build Tools

我个人习惯在 Windows 上做快速原型验证。但 Windows 的坑最多。

千万不要只装一个 MinGW 或者 Cygwin 就想糊弄过去。mujoco-py 的编译脚本写死了要用 MSVC（微软的 C++ 编译器）。

我曾经踩过的坑：一开始我装了 MinGW，结果编译到一半报错找不到 windows.h。后来换了 MSVC，又因为没装“C++ CMake tools for Windows”组件，导致 CMake 找不到编译器。折腾了一整天。

正确的做法是：

去微软官网下载 Visual Studio Build Tools 2022（或者 2019，都行）。
安装时，务必勾选 “使用 C++ 的桌面开发” 工作负载。
在右侧的“安装详细信息”里，确保 “用于 Windows 的 C++ CMake 工具” 被选中。
安装完成后，打开 “Developer Command Prompt for VS 2022”，输入 cl.exe，如果能打印出版本信息，就说明环境变量配好了。

4.1.2 Linux 用户：GCC 与 CMake

Linux 下就简单多了。一条命令搞定：

sudo apt update
sudo apt install build-essential cmake

验证一下：

gcc --version
cmake --version

这里要注意 GCC 的版本。我记得 mujoco-py 2.1.x 版本对 GCC 版本比较敏感，太新的（比如 GCC 12）或者太旧的（GCC 5）都可能出问题。建议用 GCC 7 到 GCC 10 之间的版本。

小技巧：如果你系统自带的 GCC 版本太高，可以用 sudo apt install gcc-9 g++-9 安装指定版本，然后通过 update-alternatives 切换默认版本。

4.2 安装 mujoco-py

编译器搞定后，安装本身其实就一行命令。但顺序很重要。

第一步：确保 MuJoCo 的二进制文件已经下载并解压好了。

如果你还没做这一步，请先回到上一章，把 MuJoCo 的 mujoco210 文件夹放到 ~/.mujoco/ 目录下（Linux/macOS）或者 C:\.mujoco\ 目录下（Windows）。

第二步：设置环境变量（关键！）

mujoco-py 在编译时需要找到 MuJoCo 的库文件。所以必须设置 LD_LIBRARY_PATH（Linux）或 PATH（Windows）。

Linux/macOS 用户，在 ~/.bashrc 或 ~/.zshrc 里加上：

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/.mujoco/mujoco210/bin
export MUJOCO_KEY_PATH=$HOME/.mujoco${MUJOCO_KEY_PATH}

然后 source ~/.bashrc 使其生效。

Windows 用户，在系统环境变量里添加：

变量名：MUJOCO_PATH，变量值：C:\.mujoco\mujoco210
在 Path 变量里追加：C:\.mujoco\mujoco210\bin

第三步：安装 Python 依赖并编译

建议在虚拟环境里操作。我个人习惯用 conda：

conda create -n mujoco_env python=3.8
conda activate mujoco_env
pip install numpy  # mujoco-py 依赖 numpy，先装好
pip install mujoco-py

如果你用的是 Linux，这一步通常会顺利通过。如果是 Windows，嗯，请做好心理准备。

4.3 常见安装错误及解决方案

这部分是我最想跟你分享的。我把这些年遇到的、以及社区里高频出现的错误，整理成了一张表。

错误现象	根本原因	解决方案
`error: Microsoft Visual C++ 14.0 is required`	Windows 下没有安装 MSVC 编译器	安装 Visual Studio Build Tools，并确保勾选“C++ 桌面开发”
`fatal error: GL/glew.h: No such file or directory`	Linux 下缺少 OpenGL 和 GLEW 开发库	`sudo apt install libgl1-mesa-dev libglu1-mesa-dev libglew-dev`
`ImportError: libmujoco210.so: cannot open shared object file`	`LD_LIBRARY_PATH` 没有正确设置	检查环境变量，确保指向 `mujoco210/bin` 目录
`error: command 'gcc' failed with exit status 1`	GCC 版本不兼容或缺少 Python 开发头文件	安装 `python3-dev`，或切换 GCC 版本
`CMake Error: CMAKE_C_COMPILER not set`	CMake 找不到 C 编译器	Windows 下在“开发者命令提示符”中运行；Linux 下确保 `build-essential` 已安装

4.3.1 重点错误详解：Linux 下的 GLEW 问题

这个错误在 Ubuntu 20.04/22.04 上非常常见。mujoco-py 在编译时需要链接 OpenGL 的库来做离屏渲染。如果你装的是最小化系统或者 Docker 镜像，很可能缺这些库。

我曾经在配置一个 CI/CD 流水线时，就因为这个错误卡了整整一个下午。后来发现是 Docker 镜像里没装 libgl1-mesa-dev。

解决方案很简单，一条命令：

sudo apt install libgl1-mesa-dev libglu1-mesa-dev libglew-dev libosmesa6-dev

装完之后，重新 pip install mujoco-py 即可。

4.3.2 重点错误详解：Windows 下的 MSVC 版本问题

Windows 用户请注意：mujoco-py 对 MSVC 的版本有要求。我试过用 VS 2017 的 Build Tools，编译到一半报了一堆模板错误。换成 VS 2022 就好了。

另外，如果你同时装了多个版本的 VS，一定要在 “Developer Command Prompt for VS 2022” 里运行 pip install，这样才能确保 CMake 找到正确的编译器。

避坑指南：不要在普通的 CMD 或者 PowerShell 里直接运行 pip install mujoco-py。一定要先打开对应版本的“开发者命令提示符”。

4.4 验证安装是否成功

装完了，怎么知道到底能不能用？写个简单的测试脚本。

创建一个 test_mujoco.py 文件：

import mujoco_py
import os

# 加载一个内置的模型（人形机器人）
model_path = mujoco_py.utils.discover_mujoco_xml('humanoid.xml')
model = mujoco_py.load_model_from_path(model_path)
sim = mujoco_py.MjSim(model)

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

# 打印关节位置
print("仿真运行成功！")
print("关节位置：", sim.data.qpos[:6])

运行它：

python test_mujoco.py

如果看到打印出了关节位置，没有报错，恭喜你，安装成功了！

我个人习惯：我会再加一行 print(mujoco_py.__version__)，确认一下安装的版本是不是我想要的。有时候 pip 会缓存旧版本，导致装了半天还是老版本。

如果报错 No module named 'mujoco_py'，说明安装没成功，或者你当前激活的虚拟环境不对。检查一下 pip list | grep mujoco 看看有没有。

如果报错 ImportError: libmujoco210.so: cannot open shared object file，说明环境变量没生效。退出终端，重新打开，再试一次。

4.5 知识体系总览

下面这张图，帮你把整个安装流程串起来。你可以把它当作一个检查清单。

这张图把整个流程分成了四个阶段。你跟着走，每一步都验证一下，基本不会出大问题。

4.6 写在最后

安装 mujoco-py 可能是整个 MuJoCo 学习过程中最磨人的一步。但相信我，一旦你跨过这个坎，后面的路会非常顺畅。我见过太多人卡在这一步就放弃了，真的很可惜。

如果你按照上面的步骤操作，还是报错，别慌。把错误信息复制到搜索引擎里，加上“mujoco-py”关键词，99% 的问题都能找到答案。剩下的 1%，嗯，可能就是玄学了——重启一下电脑试试。