如何在 Jupyter Notebook 中正确导入 Gym 环境库

本文详解解决 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，该包不会自动生效。请按顺序排查：

Calliper 文档对比神器

文档内容对比神器

下载

• 检查当前 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

? 总结与最佳实践

? 最后提醒：OpenAI 已不再维护 gym 包，所有安全更新、新环境（如 ALE, Box2D 扩展）及 PyPI 发布均仅面向 Gymnasium。坚持使用 gymnasium 是保障长期稳定性的唯一选择。