本文详解解决 Jupyter Notebook 中 ImportError: No module named 'gym' 的核心方法，涵盖环境匹配、库名变更（Gym → Gymnasium）、路径验证与重装策略，助你快速恢复强化学习实验环境。
本文详解解决 jupyter notebook 中 `importerror: no module named 'gym'` 的核心方法，涵盖环境匹配、库名变更（gym → gymnasium）、路径验证与重装策略，助你快速恢复强化学习实验环境。
自 2023 年起，OpenAI 官方正式将 gym 库移交至 Gymnasium 组织维护，并于 v0.27.0 版本起停止对旧版 gym（绝大多数情况并非安装失败，而是环境错配或导入方式过时所致。
✅ 正确做法：优先迁移到 Gymnasium
新版推荐使用 gymnasium 作为标准包名，语义兼容且功能增强：
# ✅ 推荐：安装并导入 gymnasium（替代原 gym）
!pip install gymnasium
import gymnasium as gym # 注意：不是 import gym
# 验证安装
env = gym.make("CartPole-v1")
print(env.action_space) # 输出正常即表示成功⚠️ 注意：gymnasium 与旧版 gym 不兼容共存。若已安装旧版 gym，建议先卸载以避免冲突：
pip uninstall gym -y pip install gymnasium
? 常见陷阱排查清单
-
内核不匹配：Jupyter Notebook 可能运行在默认 Python 内核，而非你安装 gymnasium 的 conda 环境。请确认：
import sys print(sys.executable) # 查看当前内核路径
若路径非目标环境（如 /opt/anaconda3/bin/python），需在对应环境中安装 ipykernel 并注册内核：
conda activate myenv pip install ipykernel python -m ipykernel install --user --name myenv --display-name "Python (myenv)"
然后在 Notebook 顶部菜单：Kernel → Change kernel → Python (myenv)。
未重启内核：安装后务必 Kernel → Restart & Clear Output，否则 Python 缓存可能仍报错。
-
镜像源或权限问题：国内用户建议使用清华源加速安装：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ gymnasium
? 总结
| 场景 | 解决方案 |
|---|---|
| 新项目启动 | 直接 pip install gymnasium + import gymnasium as gym |
| 旧代码迁移 | 替换所有 import gym 为 import gymnasium as gym，并检查 API 变更（如 env.reset() 现返回 (obs, info) 元组） |
| 多环境混乱 | 用 sys.executable 定位真实环境，统一在该环境下安装，再绑定 Jupyter 内核 |
? 补充说明：gym 已进入只读归档状态（GitHub Archive），不再修复 bug 或适配新 Python 版本。坚持使用旧版不仅面临导入失败风险，更存在安全隐患与兼容性隐患。拥抱 Gymnasium 是当前最稳健、可持续的选择。
