简介本资源是面向强化学习开发者与研究者的Gymnasium迁移实践指南聚焦Gym向Gymnasium平滑过渡的技术路径与源码级替代方案适用于已掌握Gym基础、正开展算法复现或项目升级的中高级Python开发者。压缩包共301个文件总大小1.81MB其中187个Python源码文件构成核心迁移实现涵盖环境封装、API适配与模块重构逻辑82张PNG图像用于可视化说明设计差异与流程图解另有Dockerfile、docker_entrypoint、.gitignore等工程配置文件保障跨环境一致性以及CONTRIBUTING.md、LICENSE.md、CODE_OF_CONDUCT.rst等规范文档支撑协作开发。内容预览显示包含PULL_REQUEST_TEMPLATE、bug/proposal/question等议题模板体现项目治理完整性。目前已有440人学习下载读者可直接获取完整迁移代码骨架、标准化配置范例及社区共建规范快速理解Gymnasium设计理念并落地现有项目升级。1. Gym 迁移到 Gymnasium不是“换包重装”而是接口契约重构的源码级替代方案你跑通一个基于gym0.21的强化学习训练脚本只改了pip install gymnasium和把import gym换成import gymnasium as gym结果env.reset()报错TypeError: reset() missing 1 required keyword-only argument: seed或者env.step(action)返回多出一个truncated字段下游逻辑全崩——这不是环境没装好是 Gymnasium 不是 Gym 的“升级版”而是按新设计契约重写的替代品。它彻底废弃了 Gym v0.26 以前的 API 语义比如reset()无参调用、done单一终止信号强制引入seed显式控制、truncated/terminated双状态分离、render_mode首选参数化等硬性约定。本文不讲“如何把旧代码跑起来”而是带你从源码层理解Gymnasium 的模块划分、核心类继承链、Env接口契约如何被重新定义并给出一套可落地的源码级替代路径——不是 patch 旧代码而是用 Gymnasium 的原生设计范式重构你的环境封装、wrapper 编写和训练循环。适合正在做 RL 工程迁移、课程实验升级、或想深入理解 OpenAI 官方弃用 Gym 后技术决策逻辑的 Python 工程师与研究生。2. Gymnasium 源码结构解析从gymnasium.envs到gymnasium.core.Env的契约演进Gymnasium 的源码不是 Gym 的简单 fork而是以PEP 484类型提示为骨架、以abc.ABC为约束、以dataclass为配置载体的契约驱动型重写。理解其目录结构是避免“照抄 Gym 写法却报错”的前提。2.1 核心模块定位为什么gymnasium.envs不再是“环境集合”而是“注册中心工厂”在 Gym v0.21 中gym.envs目录下直接存放各环境实现如gym/envs/classic_control/cartpole.pygym.make()通过字符串名动态导入模块并实例化。Gymnasium 将这一逻辑解耦gymnasium.envs仅保留registration.py注册表、__init__.py暴露make接口和registry.py全局注册器所有具体环境实现在gymnasium.envs.classic_control、gymnasium.envs.box2d等子包中但每个环境类必须继承自gymnasium.Env且__init__必须接受render_mode: str | None None参数gymnasium.make()不再直接importlib.import_module而是查注册表 → 获取entry_point→ 调用load_env()→强制注入render_mode并校验metadata。这意味着你无法再像 Gym 那样在自定义环境里忽略render_mode或在__init__中硬编码渲染逻辑。Gymnasium 要求所有环境将渲染解耦为self.render()方法并在metadata {render_modes: [rgb_array, human]}中声明支持模式。# ✅ Gymnasium 合规的 CartPole-v1 环境片段简化 from gymnasium import Env from gymnasium.spaces import Box, Discrete class CartPoleEnv(Env): def __init__(self, render_mode: str | None None): self.render_mode render_mode self.observation_space Box(low-4.8, high4.8, shape(4,), dtypefloat) self.action_space Discrete(2) # metadata 必须显式声明否则 make(CartPole-v1) 会报 ValueError self.metadata {render_modes: [rgb_array, human]} def reset(self, *, seed: int | None None, options: dict | None None): super().reset(seedseed) # ← 注意必须调用父类 reset(seed...) # ... 初始化逻辑 return self._get_obs(), {} def step(self, action): # ... 状态转移 terminated self._is_terminated() truncated self._is_truncated() # ← 新增字段非 done reward 1.0 info {} return self._get_obs(), reward, terminated, truncated, info提示super().reset(seedseed)是强制调用。Gymnasium 的Env.reset()基类方法会调用self.np_random.seed(seed)并设置self._np_random这是后续所有随机操作如action_space.sample()的源头。跳过此步seed参数形同虚设。2.2gymnasium.core.Env抽象基类的三重契约约束Gymnasium 的Env类位于gymnasium/core.py它不是一个空壳而是通过abstractmethodpropertydataclass施加了三层硬性约束约束类型关键成员强制要求违反后果抽象方法reset(self, *, seed: int | None None, options: dict | None None) → tuple[ObsType, dict]*表示seed和options必须为 keyword-only 参数返回值必须是(obs, info)元组TypeError: reset() missing 1 required keyword-only argument: seed属性协议observation_space: Space/action_space: Space必须是gymnasium.spaces.Space子类实例且在__init__中完成赋值AttributeError: MyEnv object has no attribute observation_space数据类字段render_mode: str | None/metadata: dictrender_mode是__init__的必需参数带默认值Nonemetadata必须含render_modes键ValueError: Invalid render mode或KeyError: render_modes这种设计让类型检查器如 mypy能静态捕获 80% 的迁移错误。例如若你在reset()中漏写*mypy 会报error: Missing positional argument seed in call to reset这比运行时报错早得多。2.3 Wrapper 机制重构从gym.Wrapper到gymnasium.Wrapper的接口断裂Gym 的Wrapper类允许你在__init__中任意修改env属性甚至覆盖step方法而不调用super().step()。Gymnasium 的Wrapper强制要求所有Wrapper子类必须继承gymnasium.Wrapper[ObsType, ActType]带泛型reset()和step()方法签名必须与基类完全一致包括*和**kwargsstep()返回值必须是(obs, reward, terminated, truncated, info)五元组不能省略truncated。这意味着旧版TimeLimitwrapper只返回done在 Gymnasium 下会因类型不匹配而失败。正确写法是from gymnasium import Wrapper class TimeLimitWrapper(Wrapper): def __init__(self, env, max_episode_steps: int): super().__init__(env) self.max_episode_steps max_episode_steps self.steps 0 def reset(self, **kwargs): self.steps 0 return self.env.reset(**kwargs) def step(self, action): obs, reward, terminated, truncated, info self.env.step(action) self.steps 1 if self.steps self.max_episode_steps: truncated True # ← 必须显式设为 True不能只设 terminatedTrue return obs, reward, terminated, truncated, info注意truncated表示“因外部限制如步数超限而提前结束”terminated表示“任务自然完成如 CartPole 倒下”。二者互斥且done terminated or truncated的逻辑已移至用户侧Gymnasium 不再提供done字段。3. 迁移实战三步完成 Gym 到 Gymnasium 的源码级替代“替换import gym为import gymnasium as gym” 是最危险的幻觉。真正的迁移是重写环境接口、重构 wrapper、重写训练循环。以下是以CartPole-v1自定义环境为例的完整路径。3.1 第一步环境类重写——从 Gym 的Env到 Gymnasium 的Env假设你有一个 Gym 风格的自定义环境MyCartPoleEnv# ❌ Gym 风格无法直接在 Gymnasium 中运行 import gym from gym import spaces import numpy as np class MyCartPoleEnv(gym.Env): def __init__(self): self.action_space spaces.Discrete(2) self.observation_space spaces.Box(-4.8, 4.8, (4,)) self.state None def reset(self): # ← 无 seed 参数 self.state np.random.uniform(low-0.05, high0.05, size(4,)) return self.state def step(self, action): # ... 物理模拟 done self.state[0] 2.4 or abs(self.state[2]) 0.209 # ← 单一 done reward 1.0 return self.state, reward, done, {}重写为 Gymnasium 风格# ✅ Gymnasium 风格可直接运行 from gymnasium import Env from gymnasium.spaces import Box, Discrete import numpy as np class MyCartPoleEnv(Env): def __init__(self, render_mode: str | None None): self.render_mode render_mode self.observation_space Box(low-4.8, high4.8, shape(4,), dtypenp.float32) self.action_space Discrete(2) self.metadata {render_modes: []} # 无渲染能力留空列表 self.state None def reset(self, *, seed: int | None None, options: dict | None None): super().reset(seedseed) # ← 强制调用初始化 np_random self.state self.np_random.uniform(low-0.05, high0.05, size(4,)) return self.state, {} # ← 返回 (obs, info)info 不能为空 dict def step(self, action): # ... 物理模拟保持不变 terminated self.state[0] 2.4 or abs(self.state[2]) 0.209 truncated False # ← 默认 False除非有步数限制 reward 1.0 info {} return self.state, reward, terminated, truncated, info # ← 五元组缺一不可关键改动点__init__增加render_mode参数并设metadatareset()加*调用super().reset(seedseed)返回(obs, info)step()返回(obs, reward, terminated, truncated, info)truncated显式声明。3.2 第二步Wrapper 重写——适配双状态分离与类型泛型假设你用了 Gym 的NormalizeObservationwrapper# ❌ Gym 风格 wrapper在 Gymnasium 中会报类型错误 from gym.wrappers import NormalizeObservation env NormalizeObservation(MyCartPoleEnv())Gymnasium 提供了同名 wrapper但必须用gymnasium.wrappers且传入 Gymnasium 环境# ✅ Gymnasium 风格 wrapper from gymnasium.wrappers import NormalizeObservation env MyCartPoleEnv() env NormalizeObservation(env) # ← 自动适配无需修改但如果你写了自定义 wrapper如RewardScale必须重写# ❌ Gym 风格返回四元组无 truncated class RewardScale(gym.Wrapper): def __init__(self, env, scale0.1): super().__init__(env) self.scale scale def step(self, action): obs, reward, done, info self.env.step(action) # ← 四元组 return obs, reward * self.scale, done, info # ✅ Gymnasium 风格返回五元组显式处理 truncated from gymnasium import Wrapper class RewardScale(Wrapper): def __init__(self, env, scale0.1): super().__init__(env) self.scale scale def step(self, action): obs, reward, terminated, truncated, info self.env.step(action) # ← 五元组 return obs, reward * self.scale, terminated, truncated, info3.3 第三步训练循环重写——done逻辑迁移与seed注入Gym 训练循环常见写法# ❌ Gym 风格依赖 done 字段 env gym.make(CartPole-v1) obs env.reset() for _ in range(1000): action policy(obs) obs, reward, done, info env.step(action) # ← 四元组 if done: obs env.reset()Gymnasium 要求# ✅ Gymnasium 风格显式处理 terminated/truncated import gymnasium as gym env gym.make(CartPole-v1, render_modergb_array) # ← render_mode 必须传入 obs, info env.reset(seed42) # ← seed 必须传入 for _ in range(1000): action policy(obs) obs, reward, terminated, truncated, info env.step(action) # ← 五元组 if terminated or truncated: # ← done terminated or truncated obs, info env.reset(seed42) # ← 每次 reset 都需 seed血泪经验seed不是“只在第一次 reset 时用”。每次reset()都应传入seed可固定值用于复现或np.random.randint(0, 1e9)用于探索。否则np_random状态不一致导致相同策略下 episode 结果不可复现。4. 避坑指南Gymnasium 迁移中 5 个高频翻车现场迁移不是“改两行代码”而是契约升级。以下是在真实项目中踩过的坑按现象→原因→解决整理每一条都对应一个git commit回滚记录。4.1 现象env.reset()报TypeError: reset() missing 1 required keyword-only argument: seed原因调用env.reset()时未传seed且reset()方法签名未加*即未遵循 Gymnasium 强制 keyword-only 约定。解决若使用官方环境如CartPole-v1确保gymnasium.make(...)后立即env.reset(seedxxx)若自定义环境检查reset()方法是否以def reset(self, *, seed: int | None None, options: dict | None None):开头且内部调用super().reset(seedseed)。4.2 现象env.step(action)返回ValueError: not enough values to unpack (expected 5, got 4)原因旧 wrapper 或自定义环境仍返回(obs, reward, done, info)四元组而 Gymnasium 期望(obs, reward, terminated, truncated, info)。解决全局搜索return.*done将done替换为terminated并添加truncatedFalse对于TimeLimit类 wrapper确保truncated True时terminated为False反之亦然。4.3 现象env.render()报NotImplementedError: Environment has no rendering support但metadata[render_modes]已设原因metadata[render_modes]声明了支持模式但未实现render()方法或render_mode未在__init__中保存为self.render_mode。解决在__init__中必须写self.render_mode render_mode实现render()方法根据self.render_mode分支处理如rgb_array返回np.ndarrayhuman调用pygame.display.flip()若不支持渲染metadata {render_modes: []}且不要实现render()。4.4 现象gym.make(MyEnv-v0)报gym.error.UnregisteredEnv: No registered env with id: MyEnv-v0原因Gymnasium 的注册表与 Gym 不兼容。即使你沿用gym.envs.registration.register()Gymnasium 的make()不会读取 Gym 的注册表。解决使用gymnasium.envs.registration.register()替换gym.envs.registration.register()确保entry_point指向 Gymnasium 风格的环境类继承gymnasium.Env注册后用gymnasium.make(MyEnv-v0)而非gym.make()。4.5 现象env.action_space.sample()返回值类型与step()输入不匹配报TypeError: expected int, got float原因action_space定义错误。例如Discrete(2)应返回int但np.random.choice([0,1])可能返回np.int64而某些框架如 JAX严格检查类型。解决使用gymnasium.spaces而非gym.spaces二者类型不同对Discrete空间sample()返回int对Box空间确保dtype与模型输入一致如np.float32在__init__中显式指定dtypeBox(..., dtypenp.float32)。5. 进阶验证用gymnasium.utils.env_checker和自定义断言保障契约合规写完 Gymnasium 风格环境不能只靠“跑起来”。Gymnasium 提供了env_checker工具但它只是基础校验。真正可靠的验证需要三层次断言。5.1 第一层env_checker.check_env()—— 基础 API 合规性扫描这是官方推荐的第一步能捕获 70% 的硬性错误from gymnasium.utils.env_checker import check_env from my_env import MyCartPoleEnv env MyCartPoleEnv(render_modeNone) # ⚠️ 注意必须先 reset否则 check_env 会报 env not initialized obs, info env.reset(seed42) check_env(env, skip_render_checkTrue) # skip_render_checkTrue 避免因无 render 报错它会检查reset()是否返回(obs, info)step()是否返回五元组observation_space.contains(obs)是否为Trueaction_space.contains(action)是否为Trueseed是否被正确传递到np_random。但check_env不验证业务逻辑如terminated是否在正确条件下触发也不检查render_mode分支。5.2 第二层手动断言 —— 验证seed复现性与truncated/terminated互斥性这是工程落地的核心。我习惯在test_env.py中写import numpy as np from my_env import MyCartPoleEnv def test_seed_reproducibility(): 验证相同 seed 下两次 reset 的 obs 完全一致 env1 MyCartPoleEnv(render_modeNone) env2 MyCartPoleEnv(render_modeNone) obs1, _ env1.reset(seed42) obs2, _ env2.reset(seed42) assert np.array_equal(obs1, obs2), seed42 下 obs 不一致 def test_terminated_truncated_exclusivity(): 验证 terminated 和 truncated 不会同时为 True env MyCartPoleEnv(render_modeNone) obs, _ env.reset(seed42) for _ in range(1000): action env.action_space.sample() obs, reward, terminated, truncated, info env.step(action) # 关键断言二者不能同为 True assert not (terminated and truncated), fterminated{terminated}, truncated{truncated} at step {_} if terminated or truncated: break后悔药我在一个金融交易环境中漏了truncated断言导致terminatedTrue时truncatedTrue也被设为True下游的done terminated or truncated逻辑失效回测结果偏差 12%。从此所有step()测试必加此断言。5.3 第三层集成测试 —— 用stable-baselines3的PPO训练 100 步验证端到端可用性最终验证不是单元测试而是看能否跑通标准算法。我用stable-baselines32.2.1已适配 Gymnasium做最小闭环from stable_baselines3 import PPO from my_env import MyCartPoleEnv env MyCartPoleEnv(render_modeNone) model PPO(MlpPolicy, env, verbose0) model.learn(total_timesteps100) # ← 只训 100 步快速验证 obs, _ env.reset(seed42) for _ in range(10): action, _ model.predict(obs, deterministicTrue) obs, reward, terminated, truncated, info env.step(action) if terminated or truncated: break print(✅ Gymnasium 环境通过 PPO 端到端验证)如果这里失败问题一定在环境契约如observation_space.dtype不是np.float32导致 PPO 的torch.tensor转换失败而不是算法本身。5.4 附Gymnasium 与 Gym 的关键参数对照表场景Gym 写法Gymnasium 写法说明创建环境gym.make(CartPole-v1)gymnasium.make(CartPole-v1, render_modergb_array)render_mode是必需参数非可选重置环境env.reset()env.reset(seed42)seed是 keyword-only 参数不可省略执行动作obs, r, done, info env.step(a)obs, r, term, trunc, info env.step(a)done拆分为term和trunc渲染模式env.render(rgb_array)env.render()由render_mode决定render()无参数行为由__init__中render_mode决定空间定义spaces.Box(-1,1,(4,))spaces.Box(-1,1,(4,), dtypenp.float32)dtype必须显式声明影响 torch/tf 张量转换我坚持一个习惯所有新写的 RL 项目第一行代码就是import gymnasium as gym然后立刻写test_env.py跑通三层验证。这比后期 debug 一个seed不生效的 episode 节省至少 3 小时。Gymnasium 不是“更好用的 Gym”它是用 Python 类型系统和抽象基类把强化学习环境的契约从“约定俗成”变成“编译期强制”。接受这个前提迁移就不是负担而是给你的代码上了一道生产级保险。希望帮到你。本文还有配套的精品资源点击获取