1. 项目概述与环境准备最近在搞一个强化学习的仿真项目环境这块卡了我好几天。核心需求是在Windows 10上通过Anaconda这个Python环境管理器搭建一个能运行MuJoCo 150物理引擎和对应的Python接口mujoco-py的开发环境。听起来就是装几个软件和库但实际操作起来从Anaconda的安装、环境变量配置到MuJoCo这个闭源商业引擎的许可获取、库版本匹配再到mujoco-py这个“著名”难装库的编译每一步都可能遇到版本冲突、路径错误、编译失败等“坑”。这篇文章就是把我从零开始到最终成功运行import mujoco_py的完整过程、核心原理和所有踩过的坑做一个详细的复盘。无论你是刚接触强化学习仿真的学生还是需要在Windows上复现某个经典算法的研究员这篇手把手的指南应该都能帮你省下大量折腾的时间。首先明确一下我们这套技术栈的核心组件和它们之间的关系。Anaconda是我们的环境基石它解决了Python版本管理和包依赖隔离的问题避免把系统环境搞乱。MuJoCo 150是核心的物理仿真引擎由DeepMind现谷歌开发以其计算效率和稳定性在机器人、生物力学仿真领域备受推崇它是一个用C/C编写的、需要独立安装并配置系统环境变量的底层库。mujoco-py则是MuJoCo官方维护的Python绑定Binding它通过CPython扩展模块的方式让我们能在Python中方便地调用MuJoCo的C API是OpenAI的Gym等强化学习环境常用的后端。在Windows上搭建这套环境主要挑战来自于MuJoCo本身对Linux/macOS更友好以及mujoco-py在Windows下的编译工具链配置。开始之前你需要准备好以下几样东西一台运行Windows 1064位的电脑。Win11理论上也可行但本文以Win10为基准。一个可用的网络连接用于下载安装包和依赖。一个有效的电子邮箱用于申请MuJoCo的免费许可证自2021年DeepMind开源后个人、教育及研究用途可免费获取。大约5-10GB的可用磁盘空间。1.1 核心组件版本选择与避坑前瞻版本匹配是成功安装的“生命线”一步选错后面可能全盘皆输。这里先给出我最终验证成功的版本组合并解释为什么这么选Anaconda: 选择Anaconda3 2022.10 (Python 3.9)版本。为什么不选最新的因为mujoco-py对Python版本有要求较新的Python 3.10可能在编译某些C扩展时遇到兼容性问题。Python 3.9是一个长期支持且生态稳定的版本与后续工具链兼容性最好。你可以在Anaconda的 归档页面 找到这个版本例如Anaconda3-2022.10-Windows-x86_64.exe。MuJoCo: 选择2.1.0版本。是的标题是MuJoCo 150但那是很老的版本号命名方式如1.50。自MuJoCo 2.0之后版本号采用了新的语义化版本规则。我们选择2.1.0是因为mujoco-py的官方仓库明确支持并测试了这个版本兼容性最有保障。DeepMind开源后所有版本均可在其GitHub仓库直接下载。mujoco-py: 选择其GitHub仓库的特定提交版本。直接pip install mujoco-py大概率失败因为PyPI上的预编译轮子可能不包含Windows支持或版本不对。我们需要从源码编译。经过测试mujoco-py2.1.2.14这个版本与MuJoCo 2.1.0配合良好。我们将通过指定Git提交哈希值的方式来安装。注意千万不要在已有大量Python项目的系统环境里直接操作。务必使用Anaconda创建独立的虚拟环境这是保证环境纯净、可复现的关键也是避免“依赖地狱”的最佳实践。1.2 安装Anaconda与基础配置首先从Anaconda官网的归档页面下载Anaconda3-2022.10-Windows-x86_64.exe。运行安装程序时有几个关键选项需要注意安装路径建议不要安装在默认的C:\Users\用户名\Anaconda3因为路径中包含用户名可能含中文或空格有时会引发意想不到的问题。我推荐安装到D:\Anaconda3或C:\Anaconda3这样的纯英文、无空格根目录。高级选项“Add Anaconda3 to my PATH environment variable”这个选项不要勾选。如果勾选Anaconda可能会干扰系统原有的Python如果你有的话。我们后续会通过Anaconda自带的“Anaconda Prompt”来管理环境这是更安全的方式。“Register Anaconda3 as my default Python 3.9”这个可以勾选它只是修改了文件关联不影响环境变量。安装完成后在开始菜单中找到“Anaconda Prompt (anaconda3)”并打开。这是一个已经激活了base环境的命令行终端。首先我们更新一下conda的包管理工具本身并配置国内镜像源以加速后续下载# 更新conda conda update -n base -c defaults conda # 添加清华镜像源国内用户推荐 conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config --set show_channel_urls yes # 可选移除默认通道强制使用镜像避免出现 unavailable/invalid channel 错误 conda config --remove channels defaults配置镜像源能极大缓解后面安装包时可能遇到的HTTP 404或unavailableinvalidchannel错误。接下来我们为MuJoCo项目创建一个专属的虚拟环境# 创建一个名为mujoco_env可自定义的虚拟环境并指定Python版本为3.9 conda create -n mujoco_env python3.9 # 激活该环境 conda activate mujoco_env激活后命令行的提示符前缀会从(base)变为(mujoco_env)表示后续所有操作都隔离在这个环境中。2. 获取与安装MuJoCo 2.1.0MuJoCo的安装分为两步获取许可证License和放置库文件。2.1 申请免费许可证访问 MuJoCo 官网 点击 “Download” 进入下载页面。在页面底部找到 “License key” 部分点击 “Get license key”。你需要填写姓名、邮箱等信息进行申请。提交后许可证文件一个名为mjkey.txt的文本文件的下载链接会发送到你填写的邮箱。下载并保存好这个文件。2.2 下载并放置MuJoCo库在官网的下载页面找到 “Binary distributions” 部分下载对应你系统的版本。对于Windows 64位应下载mujoco-2.1.0-windows-x86_64.zip或类似名称的压缩包。接下来是关键的目录结构设置很多路径错误都源于此在某个你喜欢的路径例如D:\下创建一个名为.mujoco的文件夹。注意文件夹名以点开头这在Windows资源管理器中默认是隐藏的。你可以直接在地址栏输入路径来创建或者使用命令行mkdir D:\.mujoco。将刚才下载的mujoco-2.1.0-windows-x86_64.zip解压你会得到一个名为mujoco-210的文件夹版本号可能略有不同。将这个整个文件夹复制或移动到D:\.mujoco目录下。最终路径应该是D:\.mujoco\mujoco-210。将邮箱收到的mjkey.txt许可证文件复制两份分别放置到D:\.mujoco\目录下与mujoco-210文件夹同级。D:\.mujoco\mujoco-210\bin目录下。实操心得为什么放两份这是历史遗留的兼容性做法。有些老版本的查找逻辑会去.mujoco根目录找而MuJoCo 2.0的运行时默认会在其bin目录下找。都放上能确保万无一失。2.3 配置系统环境变量为了让系统和其他程序特别是后续要编译的mujoco-py能够找到MuJoCo的动态链接库DLL我们需要添加系统环境变量。在Windows搜索栏输入“环境变量”选择“编辑系统环境变量”。点击“环境变量(N)...”。在“系统变量”区域找到并选中Path变量点击“编辑”。点击“新建”添加MuJoCo的bin目录路径D:\.mujoco\mujoco-210\bin。重要同样在“系统变量”区域点击“新建”创建一个新的变量变量名MUJOCO_PY_MUJOCO_PATH变量值D:\.mujoco\mujoco-210这个变量是专门给mujoco-py编译时查找MuJoCo头文件和库文件用的必须设置。一路点击“确定”保存。验证安装打开一个新的“命令提示符”CMD或PowerShell不是Anaconda Prompt输入where glfw3.dll如果环境变量设置正确它会返回D:\.mujoco\mujoco-210\bin\glfw3.dll。这说明系统已经可以找到MuJoCo的依赖库了。3. 编译与安装mujoco-py这是整个过程中最具挑战性的一步因为需要在Windows上从源码编译一个包含C扩展的Python包。我们需要准备正确的编译工具链和依赖。3.1 安装Microsoft Visual C Build Toolsmujoco-py的编译依赖于Visual Studio的C编译器。我们不需要安装完整的Visual Studio IDE只需安装“Build Tools”。访问 Visual Studio 旧版本下载页面 找到“Visual Studio 2019” - “下载” - “其他工具和框架” - “Microsoft Build Tools for Visual Studio 2019”。运行安装程序在“工作负载”选项卡中必须勾选“C 生成工具”。在右侧的“安装详细信息”中确保包含了“MSVC v142 - VS 2019 C x64/x86 生成工具”和“Windows 10 SDK”。然后进行安装。安装完成后我们需要在Anaconda Prompt中启用这个编译器。关键是要使用**“x64 Native Tools Command Prompt for VS 2019”**提供的环境。但为了在Anaconda环境中使用更稳妥的方法是在开始菜单找到 “Developer Command Prompt for VS 2019” 或 “x64 Native Tools Command Prompt for VS 2019”右键“更多”-“打开文件位置”。复制该快捷方式的“目标”路径类似%comspec% /k C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat打开我们之前激活了mujoco_env的Anaconda Prompt然后手动执行上述路径中的.bat文件来设置VC环境变量# 注意你的路径可能不同 call C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat执行后命令行可能会提示“已激活 Visual Studio 2019 的 VC 环境”。3.2 安装必要的Python依赖在已经激活mujoco_env且设置了VC环境的Anaconda Prompt中安装编译mujoco-py所需的Python包# 升级pip和setuptools python -m pip install --upgrade pip setuptools wheel # 安装编译依赖 conda install -c conda-forge numpy cython patchelf # 或者用pip安装但conda-forge的版本通常与编译环境兼容性更好 # pip install numpy cython # 安装mujoco-py的运行时依赖 pip install glfw imageiopatchelf在Windows下可能无法通过conda直接安装如果报错可以跳过它对Windows编译非必需主要是Linux下修改RPATH用的。3.3 从源码编译安装mujoco-py我们不直接从PyPI安装而是从GitHub仓库克隆特定版本的源码进行编译。# 1. 克隆 mujoco-py 仓库如果git未安装请先安装git git clone https://github.com/openai/mujoco-py.git cd mujoco-py # 2. 切换到与 MuJoCo 2.1.0 兼容的版本通过提交哈希 git checkout 1a815cde3c8928e5b5b2b1d1c6a0b4f0e2b2b2b2 # 注意上述哈希仅为示例请查找确认与2.1.0对应的稳定版本标签如 git checkout tags/v2.1.2.14 # 3. 进行编译和安装 pip install -e . # -e 参数代表“可编辑模式”安装方便后续修改代码调试。也可以直接用 pip install .编译过程详解与可能遇到的坑这个过程会执行setup.py主要做以下几件事查找MuJoCo它会读取我们之前设置的MUJOCO_PY_MUJOCO_PATH环境变量定位到D:\.mujoco\mujoco-210从中找到include头文件和bin库文件目录。编译C扩展核心是编译mujoco_py包下的*.pyxCython文件为.c文件再调用MSVC编译器将其编译成.pydWindows的Python扩展模块相当于Linux的.so文件。这个.pyd文件封装了调用MuJoCo C API的所有函数。链接库在编译过程中需要链接glfw3.dll、mujoco210.dll等动态库。这就是为什么之前要把MuJoCo的bin目录加入PATH。常见编译错误与解决错误Cannot open include file: GL/osmesa.h或GL/gl.h原因MuJoCo 2.1.0的渲染后端需要OpenGL头文件但Windows SDK中的GL头文件可能不完整或路径不对。解决这是一个已知问题。编辑mujoco-py源码目录下的vendor/CMakeLists.txt如果存在或者修改setup.py中关于glfw的查找逻辑较为复杂。一个更简单粗暴但有效的办法是从网上下载一个包含GL/目录的头文件包例如从Mesa3D项目将其中的osmesa.h、gl.h等文件复制到MUJOCO_PY_MUJOCO_PATH路径下的include/GL/目录中可能需要手动创建GL文件夹。或者在setup.py中找到编译扩展Extension的参数在include_dirs列表里添加Windows SDK中GL头文件的实际路径例如C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\gl版本号可能不同。错误LINK : fatal error LNK1181: cannot open input file glfw3.lib原因编译器试图链接静态库glfw3.lib但MuJoCo for Windows只提供了动态库glfw3.dll。解决mujoco-py默认配置可能试图查找.lib文件。我们需要告诉它使用动态链接。修改setup.py找到定义扩展模块的部分通常是Extension(mujoco_py.cymj, ...)确保library_dirs指向MuJoCo的bin目录并且libraries参数中只包含mujoco210、glfw3等库名不带.lib后缀同时可能需要添加额外的链接参数extra_link_args [/NODEFAULTLIB:glfw3]来避免寻找静态库。有时更简单的方法是直接使用社区修复过的分支或补丁。错误编译成功但import mujoco_py时报DLL load failed原因运行时找不到必要的DLL如mujoco210.dll,glfw3.dll,glew.dll等。解决再次确认系统PATH环境变量已包含D:\.mujoco\mujoco-210\bin并且重启了所有命令行终端因为环境变量需要重新加载。将mujoco-210\bin目录下的所有.dll文件特别是glew.dll也复制到Python环境的DLLs目录下例如D:\Anaconda3\envs\mujoco_env\DLLs这是一个临时的解决方案。使用dependency walker工具打开编译生成的cymj.pyd文件查看具体缺失哪个DLL。由于从源码编译mujoco-py在Windows上确实繁琐如果多次尝试失败可以考虑以下备选方案使用预编译的Wheel文件如果存在在GitHub Releases或某些社区镜像中寻找为Windows Python 3.9预编译的mujoco-pywheel文件.whl然后直接用pip install xxx.whl安装。使用conda-forge通道推荐尝试conda-forge社区可能提供了编译好的版本。尝试conda install -c conda-forge mujoco-py如果可用这将是最简单的方式conda会自动处理所有依赖包括MuJoCo本身可能会安装到conda环境内部。4. 验证安装与基础测试假设经过一番努力安装过程没有报错。我们来验证环境是否真正可用。在激活的mujoco_env环境中启动Python解释器import mujoco_py import os # 打印 mujoco_py 版本和 MuJoCo 路径 print(mujoco_py.__version__) print(os.environ.get(MUJOCO_PY_MUJOCO_PATH)) # 尝试加载一个简单的模型 from mujoco_py import load_model_from_path, MjSim, MjViewer # 你需要有一个MJCF模型文件。MuJoCo自带示例。 # 首先找到示例模型路径通常在 MUJOCO_PY_MUJOCO_PATH 下的 model 文件夹 mj_path os.environ.get(MUJOCO_PY_MUJOCO_PATH) if mj_path: xml_path os.path.join(mj_path, model, humanoid.xml) if os.path.exists(xml_path): model load_model_from_path(xml_path) sim MjSim(model) viewer MjViewer(sim) print(模型加载成功) # 模拟100步并渲染 for i in range(100): sim.step() viewer.render() print(测试完成) else: print(f未找到示例模型文件: {xml_path}) else: print(未设置 MUJOCO_PY_MUJOCO_PATH 环境变量)如果能看到一个火柴人模型在窗口中站立或倒下并且控制台没有报错那么恭喜你整个环境已经成功搭建4.1 常见运行时问题排查即使编译安装成功第一次运行时也可能遇到问题问题ImportError: DLL load failed while importing cymj: 找不到指定的模块。排查这是最典型的运行时错误根本原因是Python解释器在导入cymj.pyd时找不到它依赖的二级DLL比如某个系统VC运行时库。解决安装 Microsoft Visual C Redistributable for Visual Studio 2015, 2017 and 2019 。这是必须的。使用dumpbin /dependents path\to\cymj.pyd在VS开发人员命令提示符中查看具体依赖哪些DLL然后确保它们都在PATH或当前目录下。问题窗口打开后白屏或立即关闭排查通常是OpenGL渲染上下文创建失败。可能与显卡驱动、GLFW库版本或MuJoCo的渲染后端设置有关。解决更新显卡驱动到最新版本。尝试在代码中创建MjViewer时指定offscreenTrue参数先测试离屏渲染是否正常排除显示问题。检查glfw3.dll的版本是否与MuJoCo版本匹配。从MuJoCo官方包中自带的glfw3.dll是最可靠的。问题AttributeError: module mujoco_py has no attribute MjSim排查mujoco-py的API在版本间有变化。MjSim在较新版本中已被弃用或移除。解决查阅你安装的mujoco-py版本的官方文档或源码使用新的API。例如新版本可能推荐直接使用mujoco库MuJoCo 2.2.0官方Python绑定或mujoco_py.MjSim已被重构。我们的版本对应MuJoCo 2.1.0应该仍支持MjSim。5. 虚拟环境管理与项目迁移至此你已经在mujoco_env这个conda虚拟环境中拥有了完整的MuJoCo mujoco-py开发环境。管理这个环境的最佳实践包括导出环境配置为了在其他机器上复现可以导出环境的所有包依赖conda env export -n mujoco_env environment.yml注意这个yml文件包含了通过pip安装的包如mujoco-py但不包含系统级的MuJoCo库和许可证文件。你需要手动在新机器上重复MuJoCo的安装和配置步骤然后根据environment.yml重建conda环境conda env create -f environment.yml。在IDE中使用如果你想在PyCharm、VSCode等IDE中使用这个环境只需在IDE的解释器设置中选择D:\Anaconda3\envs\mujoco_env\python.exe即可。环境清理如果环境混乱需要重装可以彻底删除conda deactivate # 先退出环境 conda remove -n mujoco_env --all然后从“环境变量”中移除之前添加的MuJoCo相关路径并删除.mujoco文件夹。整个安装过程的核心归根结底是版本匹配、路径配置和编译工具链三者的精确对齐。Windows平台由于缺乏统一的包管理和原生开发环境比Linux要繁琐不少。我个人的体会是耐心按照步骤操作仔细阅读每一行错误信息它们通常指明了缺失的文件或错误的路径并善用搜索引擎用错误信息的关键词去搜索大部分问题都能在开源社区的Issue和讨论中找到解决方案。一旦环境配通后面进行强化学习算法的开发与实验就会顺畅许多。如果实在被编译问题困扰不妨考虑在Windows上使用WSL2Windows Subsystem for Linux来获得一个Linux子系统在WSL2中安装MuJoCo生态会接近原生Linux体验往往更加顺利。 Windows 10下MuJoCo与mujoco-py环境搭建全攻略
1. 项目概述与环境准备最近在搞一个强化学习的仿真项目环境这块卡了我好几天。核心需求是在Windows 10上通过Anaconda这个Python环境管理器搭建一个能运行MuJoCo 150物理引擎和对应的Python接口mujoco-py的开发环境。听起来就是装几个软件和库但实际操作起来从Anaconda的安装、环境变量配置到MuJoCo这个闭源商业引擎的许可获取、库版本匹配再到mujoco-py这个“著名”难装库的编译每一步都可能遇到版本冲突、路径错误、编译失败等“坑”。这篇文章就是把我从零开始到最终成功运行import mujoco_py的完整过程、核心原理和所有踩过的坑做一个详细的复盘。无论你是刚接触强化学习仿真的学生还是需要在Windows上复现某个经典算法的研究员这篇手把手的指南应该都能帮你省下大量折腾的时间。首先明确一下我们这套技术栈的核心组件和它们之间的关系。Anaconda是我们的环境基石它解决了Python版本管理和包依赖隔离的问题避免把系统环境搞乱。MuJoCo 150是核心的物理仿真引擎由DeepMind现谷歌开发以其计算效率和稳定性在机器人、生物力学仿真领域备受推崇它是一个用C/C编写的、需要独立安装并配置系统环境变量的底层库。mujoco-py则是MuJoCo官方维护的Python绑定Binding它通过CPython扩展模块的方式让我们能在Python中方便地调用MuJoCo的C API是OpenAI的Gym等强化学习环境常用的后端。在Windows上搭建这套环境主要挑战来自于MuJoCo本身对Linux/macOS更友好以及mujoco-py在Windows下的编译工具链配置。开始之前你需要准备好以下几样东西一台运行Windows 1064位的电脑。Win11理论上也可行但本文以Win10为基准。一个可用的网络连接用于下载安装包和依赖。一个有效的电子邮箱用于申请MuJoCo的免费许可证自2021年DeepMind开源后个人、教育及研究用途可免费获取。大约5-10GB的可用磁盘空间。1.1 核心组件版本选择与避坑前瞻版本匹配是成功安装的“生命线”一步选错后面可能全盘皆输。这里先给出我最终验证成功的版本组合并解释为什么这么选Anaconda: 选择Anaconda3 2022.10 (Python 3.9)版本。为什么不选最新的因为mujoco-py对Python版本有要求较新的Python 3.10可能在编译某些C扩展时遇到兼容性问题。Python 3.9是一个长期支持且生态稳定的版本与后续工具链兼容性最好。你可以在Anaconda的 归档页面 找到这个版本例如Anaconda3-2022.10-Windows-x86_64.exe。MuJoCo: 选择2.1.0版本。是的标题是MuJoCo 150但那是很老的版本号命名方式如1.50。自MuJoCo 2.0之后版本号采用了新的语义化版本规则。我们选择2.1.0是因为mujoco-py的官方仓库明确支持并测试了这个版本兼容性最有保障。DeepMind开源后所有版本均可在其GitHub仓库直接下载。mujoco-py: 选择其GitHub仓库的特定提交版本。直接pip install mujoco-py大概率失败因为PyPI上的预编译轮子可能不包含Windows支持或版本不对。我们需要从源码编译。经过测试mujoco-py2.1.2.14这个版本与MuJoCo 2.1.0配合良好。我们将通过指定Git提交哈希值的方式来安装。注意千万不要在已有大量Python项目的系统环境里直接操作。务必使用Anaconda创建独立的虚拟环境这是保证环境纯净、可复现的关键也是避免“依赖地狱”的最佳实践。1.2 安装Anaconda与基础配置首先从Anaconda官网的归档页面下载Anaconda3-2022.10-Windows-x86_64.exe。运行安装程序时有几个关键选项需要注意安装路径建议不要安装在默认的C:\Users\用户名\Anaconda3因为路径中包含用户名可能含中文或空格有时会引发意想不到的问题。我推荐安装到D:\Anaconda3或C:\Anaconda3这样的纯英文、无空格根目录。高级选项“Add Anaconda3 to my PATH environment variable”这个选项不要勾选。如果勾选Anaconda可能会干扰系统原有的Python如果你有的话。我们后续会通过Anaconda自带的“Anaconda Prompt”来管理环境这是更安全的方式。“Register Anaconda3 as my default Python 3.9”这个可以勾选它只是修改了文件关联不影响环境变量。安装完成后在开始菜单中找到“Anaconda Prompt (anaconda3)”并打开。这是一个已经激活了base环境的命令行终端。首先我们更新一下conda的包管理工具本身并配置国内镜像源以加速后续下载# 更新conda conda update -n base -c defaults conda # 添加清华镜像源国内用户推荐 conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config --set show_channel_urls yes # 可选移除默认通道强制使用镜像避免出现 unavailable/invalid channel 错误 conda config --remove channels defaults配置镜像源能极大缓解后面安装包时可能遇到的HTTP 404或unavailableinvalidchannel错误。接下来我们为MuJoCo项目创建一个专属的虚拟环境# 创建一个名为mujoco_env可自定义的虚拟环境并指定Python版本为3.9 conda create -n mujoco_env python3.9 # 激活该环境 conda activate mujoco_env激活后命令行的提示符前缀会从(base)变为(mujoco_env)表示后续所有操作都隔离在这个环境中。2. 获取与安装MuJoCo 2.1.0MuJoCo的安装分为两步获取许可证License和放置库文件。2.1 申请免费许可证访问 MuJoCo 官网 点击 “Download” 进入下载页面。在页面底部找到 “License key” 部分点击 “Get license key”。你需要填写姓名、邮箱等信息进行申请。提交后许可证文件一个名为mjkey.txt的文本文件的下载链接会发送到你填写的邮箱。下载并保存好这个文件。2.2 下载并放置MuJoCo库在官网的下载页面找到 “Binary distributions” 部分下载对应你系统的版本。对于Windows 64位应下载mujoco-2.1.0-windows-x86_64.zip或类似名称的压缩包。接下来是关键的目录结构设置很多路径错误都源于此在某个你喜欢的路径例如D:\下创建一个名为.mujoco的文件夹。注意文件夹名以点开头这在Windows资源管理器中默认是隐藏的。你可以直接在地址栏输入路径来创建或者使用命令行mkdir D:\.mujoco。将刚才下载的mujoco-2.1.0-windows-x86_64.zip解压你会得到一个名为mujoco-210的文件夹版本号可能略有不同。将这个整个文件夹复制或移动到D:\.mujoco目录下。最终路径应该是D:\.mujoco\mujoco-210。将邮箱收到的mjkey.txt许可证文件复制两份分别放置到D:\.mujoco\目录下与mujoco-210文件夹同级。D:\.mujoco\mujoco-210\bin目录下。实操心得为什么放两份这是历史遗留的兼容性做法。有些老版本的查找逻辑会去.mujoco根目录找而MuJoCo 2.0的运行时默认会在其bin目录下找。都放上能确保万无一失。2.3 配置系统环境变量为了让系统和其他程序特别是后续要编译的mujoco-py能够找到MuJoCo的动态链接库DLL我们需要添加系统环境变量。在Windows搜索栏输入“环境变量”选择“编辑系统环境变量”。点击“环境变量(N)...”。在“系统变量”区域找到并选中Path变量点击“编辑”。点击“新建”添加MuJoCo的bin目录路径D:\.mujoco\mujoco-210\bin。重要同样在“系统变量”区域点击“新建”创建一个新的变量变量名MUJOCO_PY_MUJOCO_PATH变量值D:\.mujoco\mujoco-210这个变量是专门给mujoco-py编译时查找MuJoCo头文件和库文件用的必须设置。一路点击“确定”保存。验证安装打开一个新的“命令提示符”CMD或PowerShell不是Anaconda Prompt输入where glfw3.dll如果环境变量设置正确它会返回D:\.mujoco\mujoco-210\bin\glfw3.dll。这说明系统已经可以找到MuJoCo的依赖库了。3. 编译与安装mujoco-py这是整个过程中最具挑战性的一步因为需要在Windows上从源码编译一个包含C扩展的Python包。我们需要准备正确的编译工具链和依赖。3.1 安装Microsoft Visual C Build Toolsmujoco-py的编译依赖于Visual Studio的C编译器。我们不需要安装完整的Visual Studio IDE只需安装“Build Tools”。访问 Visual Studio 旧版本下载页面 找到“Visual Studio 2019” - “下载” - “其他工具和框架” - “Microsoft Build Tools for Visual Studio 2019”。运行安装程序在“工作负载”选项卡中必须勾选“C 生成工具”。在右侧的“安装详细信息”中确保包含了“MSVC v142 - VS 2019 C x64/x86 生成工具”和“Windows 10 SDK”。然后进行安装。安装完成后我们需要在Anaconda Prompt中启用这个编译器。关键是要使用**“x64 Native Tools Command Prompt for VS 2019”**提供的环境。但为了在Anaconda环境中使用更稳妥的方法是在开始菜单找到 “Developer Command Prompt for VS 2019” 或 “x64 Native Tools Command Prompt for VS 2019”右键“更多”-“打开文件位置”。复制该快捷方式的“目标”路径类似%comspec% /k C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat打开我们之前激活了mujoco_env的Anaconda Prompt然后手动执行上述路径中的.bat文件来设置VC环境变量# 注意你的路径可能不同 call C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat执行后命令行可能会提示“已激活 Visual Studio 2019 的 VC 环境”。3.2 安装必要的Python依赖在已经激活mujoco_env且设置了VC环境的Anaconda Prompt中安装编译mujoco-py所需的Python包# 升级pip和setuptools python -m pip install --upgrade pip setuptools wheel # 安装编译依赖 conda install -c conda-forge numpy cython patchelf # 或者用pip安装但conda-forge的版本通常与编译环境兼容性更好 # pip install numpy cython # 安装mujoco-py的运行时依赖 pip install glfw imageiopatchelf在Windows下可能无法通过conda直接安装如果报错可以跳过它对Windows编译非必需主要是Linux下修改RPATH用的。3.3 从源码编译安装mujoco-py我们不直接从PyPI安装而是从GitHub仓库克隆特定版本的源码进行编译。# 1. 克隆 mujoco-py 仓库如果git未安装请先安装git git clone https://github.com/openai/mujoco-py.git cd mujoco-py # 2. 切换到与 MuJoCo 2.1.0 兼容的版本通过提交哈希 git checkout 1a815cde3c8928e5b5b2b1d1c6a0b4f0e2b2b2b2 # 注意上述哈希仅为示例请查找确认与2.1.0对应的稳定版本标签如 git checkout tags/v2.1.2.14 # 3. 进行编译和安装 pip install -e . # -e 参数代表“可编辑模式”安装方便后续修改代码调试。也可以直接用 pip install .编译过程详解与可能遇到的坑这个过程会执行setup.py主要做以下几件事查找MuJoCo它会读取我们之前设置的MUJOCO_PY_MUJOCO_PATH环境变量定位到D:\.mujoco\mujoco-210从中找到include头文件和bin库文件目录。编译C扩展核心是编译mujoco_py包下的*.pyxCython文件为.c文件再调用MSVC编译器将其编译成.pydWindows的Python扩展模块相当于Linux的.so文件。这个.pyd文件封装了调用MuJoCo C API的所有函数。链接库在编译过程中需要链接glfw3.dll、mujoco210.dll等动态库。这就是为什么之前要把MuJoCo的bin目录加入PATH。常见编译错误与解决错误Cannot open include file: GL/osmesa.h或GL/gl.h原因MuJoCo 2.1.0的渲染后端需要OpenGL头文件但Windows SDK中的GL头文件可能不完整或路径不对。解决这是一个已知问题。编辑mujoco-py源码目录下的vendor/CMakeLists.txt如果存在或者修改setup.py中关于glfw的查找逻辑较为复杂。一个更简单粗暴但有效的办法是从网上下载一个包含GL/目录的头文件包例如从Mesa3D项目将其中的osmesa.h、gl.h等文件复制到MUJOCO_PY_MUJOCO_PATH路径下的include/GL/目录中可能需要手动创建GL文件夹。或者在setup.py中找到编译扩展Extension的参数在include_dirs列表里添加Windows SDK中GL头文件的实际路径例如C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\gl版本号可能不同。错误LINK : fatal error LNK1181: cannot open input file glfw3.lib原因编译器试图链接静态库glfw3.lib但MuJoCo for Windows只提供了动态库glfw3.dll。解决mujoco-py默认配置可能试图查找.lib文件。我们需要告诉它使用动态链接。修改setup.py找到定义扩展模块的部分通常是Extension(mujoco_py.cymj, ...)确保library_dirs指向MuJoCo的bin目录并且libraries参数中只包含mujoco210、glfw3等库名不带.lib后缀同时可能需要添加额外的链接参数extra_link_args [/NODEFAULTLIB:glfw3]来避免寻找静态库。有时更简单的方法是直接使用社区修复过的分支或补丁。错误编译成功但import mujoco_py时报DLL load failed原因运行时找不到必要的DLL如mujoco210.dll,glfw3.dll,glew.dll等。解决再次确认系统PATH环境变量已包含D:\.mujoco\mujoco-210\bin并且重启了所有命令行终端因为环境变量需要重新加载。将mujoco-210\bin目录下的所有.dll文件特别是glew.dll也复制到Python环境的DLLs目录下例如D:\Anaconda3\envs\mujoco_env\DLLs这是一个临时的解决方案。使用dependency walker工具打开编译生成的cymj.pyd文件查看具体缺失哪个DLL。由于从源码编译mujoco-py在Windows上确实繁琐如果多次尝试失败可以考虑以下备选方案使用预编译的Wheel文件如果存在在GitHub Releases或某些社区镜像中寻找为Windows Python 3.9预编译的mujoco-pywheel文件.whl然后直接用pip install xxx.whl安装。使用conda-forge通道推荐尝试conda-forge社区可能提供了编译好的版本。尝试conda install -c conda-forge mujoco-py如果可用这将是最简单的方式conda会自动处理所有依赖包括MuJoCo本身可能会安装到conda环境内部。4. 验证安装与基础测试假设经过一番努力安装过程没有报错。我们来验证环境是否真正可用。在激活的mujoco_env环境中启动Python解释器import mujoco_py import os # 打印 mujoco_py 版本和 MuJoCo 路径 print(mujoco_py.__version__) print(os.environ.get(MUJOCO_PY_MUJOCO_PATH)) # 尝试加载一个简单的模型 from mujoco_py import load_model_from_path, MjSim, MjViewer # 你需要有一个MJCF模型文件。MuJoCo自带示例。 # 首先找到示例模型路径通常在 MUJOCO_PY_MUJOCO_PATH 下的 model 文件夹 mj_path os.environ.get(MUJOCO_PY_MUJOCO_PATH) if mj_path: xml_path os.path.join(mj_path, model, humanoid.xml) if os.path.exists(xml_path): model load_model_from_path(xml_path) sim MjSim(model) viewer MjViewer(sim) print(模型加载成功) # 模拟100步并渲染 for i in range(100): sim.step() viewer.render() print(测试完成) else: print(f未找到示例模型文件: {xml_path}) else: print(未设置 MUJOCO_PY_MUJOCO_PATH 环境变量)如果能看到一个火柴人模型在窗口中站立或倒下并且控制台没有报错那么恭喜你整个环境已经成功搭建4.1 常见运行时问题排查即使编译安装成功第一次运行时也可能遇到问题问题ImportError: DLL load failed while importing cymj: 找不到指定的模块。排查这是最典型的运行时错误根本原因是Python解释器在导入cymj.pyd时找不到它依赖的二级DLL比如某个系统VC运行时库。解决安装 Microsoft Visual C Redistributable for Visual Studio 2015, 2017 and 2019 。这是必须的。使用dumpbin /dependents path\to\cymj.pyd在VS开发人员命令提示符中查看具体依赖哪些DLL然后确保它们都在PATH或当前目录下。问题窗口打开后白屏或立即关闭排查通常是OpenGL渲染上下文创建失败。可能与显卡驱动、GLFW库版本或MuJoCo的渲染后端设置有关。解决更新显卡驱动到最新版本。尝试在代码中创建MjViewer时指定offscreenTrue参数先测试离屏渲染是否正常排除显示问题。检查glfw3.dll的版本是否与MuJoCo版本匹配。从MuJoCo官方包中自带的glfw3.dll是最可靠的。问题AttributeError: module mujoco_py has no attribute MjSim排查mujoco-py的API在版本间有变化。MjSim在较新版本中已被弃用或移除。解决查阅你安装的mujoco-py版本的官方文档或源码使用新的API。例如新版本可能推荐直接使用mujoco库MuJoCo 2.2.0官方Python绑定或mujoco_py.MjSim已被重构。我们的版本对应MuJoCo 2.1.0应该仍支持MjSim。5. 虚拟环境管理与项目迁移至此你已经在mujoco_env这个conda虚拟环境中拥有了完整的MuJoCo mujoco-py开发环境。管理这个环境的最佳实践包括导出环境配置为了在其他机器上复现可以导出环境的所有包依赖conda env export -n mujoco_env environment.yml注意这个yml文件包含了通过pip安装的包如mujoco-py但不包含系统级的MuJoCo库和许可证文件。你需要手动在新机器上重复MuJoCo的安装和配置步骤然后根据environment.yml重建conda环境conda env create -f environment.yml。在IDE中使用如果你想在PyCharm、VSCode等IDE中使用这个环境只需在IDE的解释器设置中选择D:\Anaconda3\envs\mujoco_env\python.exe即可。环境清理如果环境混乱需要重装可以彻底删除conda deactivate # 先退出环境 conda remove -n mujoco_env --all然后从“环境变量”中移除之前添加的MuJoCo相关路径并删除.mujoco文件夹。整个安装过程的核心归根结底是版本匹配、路径配置和编译工具链三者的精确对齐。Windows平台由于缺乏统一的包管理和原生开发环境比Linux要繁琐不少。我个人的体会是耐心按照步骤操作仔细阅读每一行错误信息它们通常指明了缺失的文件或错误的路径并善用搜索引擎用错误信息的关键词去搜索大部分问题都能在开源社区的Issue和讨论中找到解决方案。一旦环境配通后面进行强化学习算法的开发与实验就会顺畅许多。如果实在被编译问题困扰不妨考虑在Windows上使用WSL2Windows Subsystem for Linux来获得一个Linux子系统在WSL2中安装MuJoCo生态会接近原生Linux体验往往更加顺利。