本文详解解决 jupyter notebook 中 importerror: no module named 'gym' 的根本原因与实操方案，涵盖 gym 迁移至 gymnasium、内核环境匹配、路径验证及重装策略，助你快速恢复强化学习开发环境。
本文详解解决 jupyter notebook 中 importerror: no module named 'gym' 的根本原因与实操方案，涵盖 gym 迁移至 gymnasium、内核环境匹配、路径验证及重装策略，助你快速恢复强化学习开发环境。
自 2023 年起，原 OpenAI Gym 项目已正式移交并重构为 Gymnasium（由 Farama Foundation 维护），原 gym 包（v0.26.x 及更早）停止维护，而 v0.27.0+ 版本仅作为 Gymnasium 的兼容别名存在。因此，你在终端能成功运行 pip install gym，却在 Jupyter 中报错 No module named 'gym'，大概率并非安装失败，而是以下三类问题叠加所致：
✅ 1. 使用已弃用的 import gym 语句（最常见原因）
当前推荐方式是显式导入 Gymnasium 并按需 alias 为 gym：
# ✅ 推荐：安装并导入 Gymnasium（官方继任者）
!pip install gymnasium
import gymnasium as gym # 标准写法，完全兼容原 gym API
env = gym.make("CartPole-v1", render_mode="rgb_array")⚠️ 注意：pip install gym 在新版本中实际安装的是 Gymnasium 的兼容层，但必须通过 import gymnasium as gym 显式导入，直接 import gym 会因模块命名空间未注册而失败（尤其在未重启内核时）。
✅ 2. Jupyter 内核与 Python 环境不一致
即使你在终端执行了 pip install gymnasium，若 Jupyter 使用的是其他 conda 虚拟环境或系统 Python，该包不会自动生效。请按顺序排查：
-
检查当前 notebook 使用的内核：
import sys print(sys.executable) # 输出类似 /opt/anaconda3/envs/rl/bin/python
-
确保在同一环境中安装：
# 在终端中，先激活对应环境（如使用 conda） conda activate rl pip install gymnasium --upgrade # 或直接在 notebook 单元格中强制安装到当前内核（推荐） !{sys.executable} -m pip install gymnasium --upgrade
✅ 3. 缓存/路径冲突导致模块未识别
曾手动降级 Anaconda 或混用 pip/conda 安装易引发路径混乱。可执行以下清理步骤：
- 重启 Jupyter 内核（Kernel → Restart & Clear Output）；
- 清除 Python 缓存：
import importlib import sys if 'gym' in sys.modules: del sys.modules['gym'] if 'gymnasium' in sys.modules: del sys.modules['gymnasium'] - 验证安装状态：
!{sys.executable} -m pip list | grep -i "gym" # 应输出：gymnasium 0.29.1
? 总结与最佳实践
| 场景 | 推荐操作 |
|---|---|
| 新项目启动 | 直接 pip install gymnasium + import gymnasium as gym |
| 迁移旧代码 | 全局替换 import gym → import gymnasium as gym，无需修改 gym.make() 等调用 |
| 多环境管理 | 始终通过 sys.executable 确认目标环境，避免 pip install 到错误 Python 解释器 |
| 持续集成 | 在 requirements.txt 中明确写入 gymnasium>=0.27.0，而非 gym |
? 最后提醒：OpenAI 已不再维护 gym 包，所有安全更新、新环境（如 ALE, Box2D 扩展）及 PyPI 发布均仅面向 Gymnasium。坚持使用 gymnasium 是保障长期稳定性的唯一选择。
