1. 为什么你的gym==0.18.3死活装不上？一个被忽略的“元凶”
最近在复现一些经典的强化学习项目时，我发现很多老教程都指定要安装 gym==0.18.3 这个版本。这很正常，毕竟不同版本的API变动可能会让旧代码直接跑不起来。但当我信心满满地敲下 pip install gym==0.18.3 时，迎接我的不是成功的提示，而是一段令人头疼的报错。我相信很多朋友都遇到过类似的情况，错误信息大概长这样：
error: subprocess-exited-with-error
× python setup.py egg_info did not run successfully.
...
error in gym setup command: 'extras_require' must be a dictionary whose values are strings or lists of strings containing valid project/version requirement specifiers.
一开始，我和大多数人一样，去网上搜解决方案。主流的方法无非是“三板斧”：降级 setuptools、降级 wheel、或者换用 conda 安装。我老老实实地试了一遍，把 setuptools 降到40、50的版本，wheel 也换了几个老版本，结果呢？错误依旧，纹丝不动。这时候我才意识到，问题可能没那么简单，它可能不是由我当前环境引起的，而是这个古老安装包本身的“先天缺陷”。
这个错误的核心信息其实很明确：setup.py 文件中的 extras_require 参数格式不符合新版本 setuptools 的规范。gym 0.18.3 发布于2021年初，而如今（2025年）我们使用的 setuptools 版本可能已经迭代了数十个版本，对打包元数据的校验更加严格。这就好比一本2010年出版的书籍，里面的排版规则在2025年的新印刷标准下被判定为“不规范”，导致无法印刷。直接 pip install 会触发包构建过程，而构建时使用的正是你当前环境中较新的 setuptools，于是格式冲突就发生了。
所以，网上那些降级 setuptools 的方法，思路是对的，但成功率不高，因为它依赖于找到一个恰好能与 gym 0.18.3 原始 setup.py 兼容的、非常古老的 setuptools 版本，这个版本可能还与你环境中其他现代包的要求冲突。更根本、更一劳永逸的办法，是直接去修正那本“书”的排版规则——也就是手动修改 gym 源码包里的 setup.py 文件。接下来，我就带你完整走一遍这个“手术”过程，从下载源码、诊断问题、动刀修改，到最终成功安装验证。
2. 实战第一步：获取并解压gym 0.18.3的源码包
既然要修改，我们首先得拿到 gym 0.18.3 的源代码。最直接的方式是从 PyPI 上下载它的源码发行包（sdist）。
2.1 手动下载源码包
打开你的浏览器，访问 PyPI 上 gym 的项目页面。你可以直接搜索 “gym pypi”，或者访问类似 pypi.org/project/gym/ 的地址（请注意使用官方和正规的软件源）。在页面上找到版本历史，选择 0.18.3。通常你会看到几个下载链接，其中扩展名为 .tar.gz 的就是源码包。它的名字一般是 gym-0.18.3.tar.gz。点击下载它，或者复制链接地址，用 wget 或 curl 命令下载。
我更习惯用命令行操作，一气呵成。如果你在 Linux 或 macOS 的终端里，或者 Windows 上使用了 Git Bash、WSL，可以执行：
wget https://files.pythonhosted.org/packages/1a/db/816fd52c0c196b6799e89d1f65b6c74fead2707cf7d447f3f354edfa7a44/gym-0.18.3.tar.gz
如果 wget 不可用，用 curl 也可以：
curl -O https://files.pythonhosted.org/packages/1a/db/816fd52c0c196b6799e89d1f65b6c74fead2707cf7d447f3f354edfa7a44/gym-0.18.3.tar.gz
下载完成后，你会在当前目录看到一个大约1.6MB的 gym-0.18.3.tar.gz 文件。
2.2 解压源码包
接下来，我们需要把这个压缩包解压，看看里面的结构。使用 tar 命令：
tar -xzf gym-0.18.3.tar.gz
解压后，会生成一个名为 gym-0.18.3 的文件夹。我们进入这个文件夹：
cd gym-0.18.3
现在，用 ls 命令看一眼目录内容，你应该能看到一系列标准的 Python 项目文件，其中最关键的就是 setup.py，还有 README.md、gym 源码目录等。我们的所有操作都将围绕这个 setup.py 展开。在动手修改前，我强烈建议你先备份一下原始文件，比如复制一份叫 setup.py.backup，这样万一改错了还能回头。
3. 深入病灶：解读setup.py中的extras_require格式错误
找到 setup.py 后，先别急着改。我们得搞清楚它到底哪里出了问题，这样修改起来才有底气。用你喜欢的文本编辑器（VSCode、Vim、Sublime，甚至记事本都行）打开它。文件开头部分是关于导入和版本信息，我们快速滚动到 setup() 函数调用那里。
在原始的 gym 0.18.3 的 setup.py 中，关于依赖定义的部分，特别是 extras_require，是长这样的（这是问题代码的简化示意）：
extras = {
'atari': ['atari_py~=0.2.0', 'opencv-python>=3'],
'box2d': ['box2d-py~=2.3.5'],
'classic_control': [],
'mujoco': ['mujoco_py>=1.50,<2.0', 'imageio'],
'robotics': ['mujoco_py>=1.50,<2.0', 'imageio'],
}
# ... 可能还有一些后续处理
extras['all'] = list(set([dep for deps in extras.values() for dep in deps]))
extras['nomujoco'] = list(set([dep for key, deps in extras.items() if key not in ['mujoco', 'robotics'] for dep in deps]))
setup(
...
extras_require=extras,
...
)
问题就出在后续对 extras 字典的修改上。注意看 extras['all'] 和 extras['nomujoco'] 这两行。它们使用了集合（set()）来合并和去重依赖列表。在 Python 中，set() 对象是一个无序的、不重复的元素集。关键点来了：set() 对象本身并不是字符串或字符串列表，它是一个集合类型的对象。
新版本的 setuptools 在解析 setup() 参数时，会严格检查 extras_require 字典里的每一个值。它要求每个值必须是 字符串（表示一个依赖）或者 字符串列表（表示一组依赖）。而一个 set 对象，即使它里面装的都是字符串，其类型也是 set，不符合规范。这就触发了我们看到的错误：'extras_require' must be a dictionary whose values are strings or lists of strings...
所以，修复方法非常直接：我们需要确保 extras['all'] 和 extras['nomujoco'] 的值是列表（list），而不是集合（set）。代码里虽然用了 list(set(...)) 进行了转换，但有时候在复杂的推导式或某些Python版本环境下，可能依然存在歧义或中间状态问题。最稳妥的方式，就是按照新规范，清晰地定义一个格式完全正确的 extras 字典。
4. 手把手修改：替换为修复后的setup.py代码
理解了原理，修改就很简单了。我们不需要重写整个文件，只需要用一份格式正确的代码替换掉原来的 setup.py 内容。下面这份代码是我在多次实战中验证过的，它直接明确了 extras 字典的结构，确保每个键对应的值都是列表。
请你完全清空原有的 setup.py 文件内容，将以下代码完整地复制粘贴进去，然后保存。
from setuptools import setup, find_packages
import sys
import os.path
# Don't import gym module here, since deps may not be installed
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'gym'))
from version import VERSION
# Environment-specific dependencies.
extras = {
'atari': ['atari_py~=0.2.0', 'opencv-python>=3'],
'box2d': ['box2d-py~=2.3.5'],
'classic_control': [],
'mujoco': ['mujoco_py>=1.50,<2.0', 'imageio'],
'robotics': ['mujoco_py>=1.50,<2.0', 'imageio'],
}
# Meta dependency groups.
# 关键修复：确保 extras['nomujoco'] 和 extras['all'] 是列表（list）类型
# 使用集合推导式去重，然后立即转换为列表
nomujoco_deps = []
for name, group in extras.items():
if name not in {'mujoco', 'robotics'}:
nomujoco_deps.extend(group)
extras['nomujoco'] = list(set(nomujoco_deps)) # 去重后转为列表
all_deps = []
for group in extras.values():
all_deps.extend(group)
extras['all'] = list(set(all_deps)) # 去重后转为列表
setup(
name='gym',
version=VERSION,
description='The OpenAI Gym: A toolkit for developing and comparing your reinforcement learning agents.',
url='https://github.com/openai/gym',
author='OpenAI',
author_email='gym@openai.com',
license='',
packages=[package for package in find_packages() if package.startswith('gym')],
zip_safe=False,
install_requires=[
'scipy',
'numpy>=1.10.4',
'pyglet>=1.4.0,<=1.5.15',
'Pillow<=8.2.0',
'cloudpickle>=1.2.0,<1.7.0',
],
extras_require=extras, # 这里传入的extras已经是一个值全为列表的字典
package_data={
'gym': [
'envs/mujoco/assets/*.xml',
'envs/classic_control/assets/*.png',
'envs/robotics/assets/LICENSE.md',
'envs/robotics/assets/fetch/*.xml',
'envs/robotics/assets/hand/*.xml',
'envs/robotics/assets/stls/fetch/*.stl',
'envs/robotics/assets/stls/hand/*.stl',
'envs/robotics/assets/textures/*.png'
]
},
tests_require=['pytest', 'mock'],
python_requires='>=3.6',
classifiers=[
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7',
'Programming Language :: Python :: 3.8',
'Programming Language :: Python :: 3.9',
],
)
这段代码的核心改动点：
- 清晰的定义：
extras基础字典保持不变，它定义了几个核心环境组的依赖。 - 安全的合并与转换：在创建
extras['nomujoco']和extras['all']时，我使用了更清晰的循环语法来收集依赖项，然后通过list(set(...))进行去重并显式地转换为列表。虽然看起来和原版逻辑相似，但这样写避免了在复杂推导式中可能产生的类型歧义，确保最终赋值给字典的值是一个纯粹的list对象。 - 兼容性：保留了所有原始依赖的版本范围，确保与
gym 0.18.3的功能完全兼容。
保存文件后，我们的“手术”就完成了。接下来就是安装和验证。
5. 从修改到安装：完成本地构建与验证
现在，我们位于修改后的 gym-0.18.3 目录下。接下来进行本地安装。
5.1 执行本地安装
打开你的终端（Windows用户如果用Anaconda，请打开Anaconda Prompt或PowerShell，并激活目标环境），确保当前工作目录就是包含修改后的 setup.py 的 gym-0.18.3 文件夹。
执行安装命令：
pip install .
这个点 . 代表当前目录。pip 会读取当前目录下的 setup.py 文件，执行构建和安装过程。这次，你应该不会再看到那个令人沮丧的 extras_require 格式错误了。安装过程会正常下载并安装 gym 及其核心依赖（如 numpy, scipy, pyglet, cloudpickle 等）。
安装成功的输出末尾会类似这样：
Successfully built gym
Installing collected packages: pyglet, scipy, cloudpickle, gym
Successfully installed cloudpickle-1.6.0 gym-0.18.3 pyglet-1.5.15 scipy-1.10.1
如果你之前安装过其他版本的 gym，pip 会先卸载它们，然后安装我们的 0.18.3 版本。
5.2 验证安装结果
安装完成后，强烈建议进行两步验证，确保万无一失。
第一步，使用 pip show 检查包信息：
pip show gym
如果安装成功，你会看到类似下面的输出，特别注意 Version 字段应该是 0.18.3：
Name: gym
Version: 0.18.3
Summary: The OpenAI Gym: A toolkit for developing and comparing your reinforcement learning agents.
Home-page: https://github.com/openai/gym
Author: OpenAI
Author-email: gym@openai.com
License:
Location: /your/python/path/site-packages
Requires: cloudpickle, numpy, Pillow, pyglet, scipy
Required-by:
第二步，运行一个简单的Python交互式测试：
打开Python解释器，尝试导入 gym 并创建一个最简单的环境：
import gym
print(gym.__version__) # 应该输出 0.18.3
env = gym.make('CartPole-v1')
print(env.observation_space) # 应该输出 Box([...], [...], (4,), float32)
env.close()
如果以上两步都顺利通过，那么恭喜你！你已经成功解决了 gym==0.18.3 的安装难题。
6. 避坑指南与扩展思考：关于环境管理的经验之谈
虽然通过修改 setup.py 我们解决了眼前的问题，但在实际开发和研究中，环境管理本身就是一个大课题。这里分享几个我踩过坑后总结的经验，希望能帮你避开一些弯路。
首先，关于Python版本。 gym 0.18.3 官方支持 Python 3.6 到 3.9。我强烈建议使用 Python 3.8 或 3.9，这是一个在兼容性和库支持上比较平衡的版本。太新的版本（如3.11+）可能会遇到其他依赖包的不兼容问题，而太旧的版本（如3.6）则可能被一些新工具链逐渐抛弃。
其次，虚拟环境是必须的。 永远不要在你的系统基础Python环境里直接安装项目依赖。使用 venv、virtualenv 或者 conda 创建独立的虚拟环境。这样做的好处是，每个项目都有自己的依赖沙箱，不会互相污染。例如，你今天安装 gym 0.18.3 修改了 setuptools 的某些隐式约定，明天另一个项目可能需要最新版的 setuptools，隔离环境就能完美解决冲突。我个人的习惯是，每个重要的实验或项目，都对应一个独立的 conda 环境，环境名和项目名一致，一目了然。
再者，理解依赖冲突的本质。 这次 extras_require 的错误，本质上是软件包生态中“向前兼容”的挑战。旧包按照旧的规范编写，而新工具按照新的、更严格的规范来检查。这类问题在未来还会遇到。除了修改源码，还有另一种思路是“锁定构建环境”，即使用一个与旧包时代匹配的、非常古老的 setuptools 和 wheel 版本去构建它。这就是为什么网上流传降级 setuptools 的方法。你可以通过 pip install setuptools==45.2.0 wheel==0.34.2 这样的命令尝试，但正如我前面所说，这个方法成功率不稳定，因为它可能与你环境中其他需要新版本 setuptools 的包冲突。两相比较，直接修改有问题的源码包，是更精准、更可控的方案。
最后，关于“Atari”等扩展环境的安装。 我们成功安装了 gym 的核心。但如果你想运行 Atari 游戏（如 Breakout-v4），还需要安装 atari 组的额外依赖。根据我们修改后的 setup.py，你可以用以下命令安装：
pip install gym[atari]==0.18.3
注意，由于我们是本地修改后安装的，pip 可能会从已安装的包中读取元数据，而不会重新构建。最稳妥的方式是，在最初安装时就直接指定扩展：
# 在修改好setup.py的目录下，执行：
pip install .[atari]
# 或者安装所有额外依赖（不推荐，因为会装很多你可能用不上的包）
# pip install .[all]
安装 atari 组会拉取 atari_py 和 opencv-python，这个过程可能会因为网络或编译问题遇到新的挑战，但那已经是另一个故事了。至少，我们已经跨过了安装 gym 核心的最大障碍。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
