简介本资源是面向强化学习开发者与研究者的Gymnasium迁移实践指南专为熟悉OpenAI Gym但需平滑过渡至新标准框架的Python工程师设计解决API变更、环境重构与项目适配等核心迁移难题。压缩包共301个文件1.81MB含187个Python源码文件覆盖环境封装、空间定义、向量化接口等关键模块、82张PNG图像含架构图与流程示意图、12个XML配置及Dockerfile、docker_entrypoint等容器化部署文件以及CONTRIBUTING.md、LICENSE.md、PULL_REQUEST_TEMPLATE.md等工程规范文档。已有421人学习下载资源结构完整呈现Gymnasium官方维护的代码组织逻辑与迁移路径既包含可直接复用的替代实现也提供从Gym API到Gymnasium v0.27的逐层转换说明、测试验证脚本和典型环境重写范例助力用户快速掌握新版设计哲学并完成存量项目升级。 Gymnasium 这个名字这两年只要玩强化学习的基本都绕不开。如果你打开一个老项目发现里面还是import gym然后跑起来报了一堆环境注册的警告甚至直接崩溃那你大概率正面临一次从 OpenAI Gym 到 Gymnasium 的迁移。这个迁移不是简单的换一个 pip 包名它涉及环境接口签名、Wrappers 机制、Space 类型检查、以及底层向量化实现等一系列改动。我最近把几个线上用的强化学习训练脚本从 Gym 迁到了 Gymnasium顺手把一套基于 Gym 接口封装的自研环境也改过来了整个过程踩了不少坑也沉淀了一些可复用的替换思路。这篇文章就把这次迁移的完整方案拆开讲清楚重点说说源码层面怎么改、API 差异背后的设计意图、以及如何用一套替代方案平滑过渡不中断现有训练流程。1. 内容整体设计与思路拆解1.1 为什么必须迁Gym 停更与 API 分裂的必然性先交代一下背景。OpenAI Gym 在强化学习领域的历史地位不用多说但它实际上在 2021 年前后就基本停止了积极维护后由 Farama Foundation 接手并改名为 Gymnasium。这个接过接力棒的项目不只是换个名字而是把原来 Gym 里很多悬而未决的设计问题一并解决掉。最直接的影响就是老 Gym 的 API 在0.26版本里引入了新的 step 接口返回五元组但这套新接口和早期的四元组接口并存了很久导致大量开源代码和自研代码要么基于旧接口写要么在不同版本之间打架。而 Gymnasium 直接统一为五元组并把 reset 接口的签名也规范了等于把这段历史债务一次性切掉。从实际项目维护的角度看不迁移的代价会随着时间增长越来越大。一方面Gym 的 PyPI 包已经停止更新依赖它的项目在 Python 新版本环境下会出现兼容性问题比如distutils的移除就直接让 Gym 在 Python 3.12 上安装失败。另一方面社区生态的重心已经完全转移到 Gymnasium 上最新的强化学习库、Rendering 工具、环境集合都以它为基准。如果只守着老代码新算法接不进来新环境用不了慢慢就变成一座孤岛。所以迁移不是赶时髦而是现实倒逼。1.2 替代方案的整体设计思路兼容层 增量改造我做迁移时定的原则不是“推倒重来”而是“兼容层 增量改造”。所谓兼容层就是在不改变原有训练脚本调用方式的前提下把底层环境库和 Gymnasium 的接口对齐。具体做到两层自定义环境类仍然通过gymnasium.Env继承但对外暴露的方法名、参数顺序尽量与老 Gym 保持一致减少上层策略代码的改动面。训练脚本里统一通过gymnasium.make注册和创建环境不再直接gym.make。如果需要兼容老代码里残留的gym.make调用就做一个轻量级的别名模块把gym重定向到gymnasium。对应到源码层面会有一份改动清单env.seed()改为env.reset(seed...)env.step()的返回值从四元组改为五元组注意接收terminated和truncated这两个布尔值env.render()的调用方式从env.render(modehuman)改为env.render()配合构造时的render_mode参数observation_space和action_space从gym.spaces改成gymnasium.spaces类型声明和抽样行为也有细微差别。这套设计的优势在于训练代码、算法代码、评估代码三个层面可以分步改造每完成一步就回归测试不会出现一次迁移就要把所有代码全部改完、牵一发动全身的局面。而且由于 Gymnasium 本身保持了相当比例的老接口兼容性比如gymnasium.make的用法基本迁移过来就能跑实际迁移成本比想象中低不少。1.3 迁移前必须做好的资源盘点迁移前先盘点手里的代码资产这一步省不得。建议列一个清单把项目里所有直接或间接依赖 Gym 的模块找出来包括直接import gym的模块、通过gym.make创建环境的脚本、注册了自定义环境的包、使用了gym.spaces的观测和动作定义、依赖gym.Wrapper的封装层、以及引用了gym.utils.seeding等工具函数的代码。我当时用一个简单的 grep 命令先扫一遍grep -rn import gym\|from gym --include*.py | grep -v .venv | grep -v .git再把结果按模块分组估计每个文件的改动量。这一步的意义在于避免迁移到一半才发现某个深层依赖没考虑到比如一个 Wrapper 里偷偷用了env.unwrapped的某种老行为或者在某个角落直接调用了gym.logger。这些隐藏依赖在迁移前往往不会被注意到但在切换之后就会变成难以排查的坑。另外别忘了检查环境中是否存在多个 Gym 版本混用的情况。比如主环境装了gymnasium但某个子模块的 venv 里还锁定着一个老版gym。这类版本冲突比 API 改写更隐蔽因为它可能只在特定路径下被触发。我建议在迁移期间把所有虚拟环境统一重建并把 Gym 相关依赖固定为 Gymnasium 之后跑一遍全量测试避免新旧两套库交错调用。2. 核心细节解析与实操要点2.1 从 gym.Env 到 gymnasium.Env继承方式与接口变化先说最底层的环境类。老 Gym 的环境类定义长这样import gym from gym import spaces class MyEnv(gym.Env): def __init__(self): self.action_space spaces.Discrete(2) self.observation_space spaces.Box(low0, high1, shape(4,))同样的类在 Gymnasium 下需要改成import gymnasium as gym from gymnasium import spaces class MyEnv(gym.Env): def __init__(self, render_modeNone): self.action_space spaces.Discrete(2) self.observation_space spaces.Box(low0, high1, shape(4,)) self.render_mode render_mode一眼看上去改动不大但有几个关键点需要特别留意。第一个是metadata里的render_modes字段。Gymnasium 的环境类通常需要在类级别定义这个字段否则在构造时传render_mode会触发警告虽然不会直接报错但属于不规范行为。具体定义方式class MyEnv(gym.Env): metadata {render_modes: [human, rgb_array], render_fps: 30}第二个是reset方法的签名。老 Gym 的reset通常没有参数或者接受一个可选的seed。Gymnasium 的规范是def reset(self, *, seedNone, optionsNone): super().reset(seedseed) # 初始化状态 self.state ... info {} return self._get_obs(), info这里有两个细节。一是seed和options都是强制关键字参数不能写成位置参数二是必须调用super().reset(seedseed)来重置父类内部的状态包括np_random。如果漏掉这行环境虽然能跑但是随机种子永远不会生效实验结果无法复现。这个坑很隐蔽因为老 Gym 里很多环境根本不调用super().reset()迁移后不补上就会出问题。第三个是step方法的返回值。老 Gym 0.25 及之前的版本返回(obs, reward, done, info)四元组0.26 引入了五元组但需要额外传new_step_apiTrueGymnasium 直接统一为五元组def step(self, action): # 执行动作更新状态 terminated ... truncated ... reward ... info {} return self._get_obs(), reward, terminated, truncated, infoterminated表示任务是否因达成目标或进入终端状态而结束truncated表示是否因超过步数上限、超出边界等外部条件而强制截断。这两者的语义区别很重要尤其是在处理稀疏奖励任务时如果算法分不清这两个布尔值timeout 会被错误地当成任务失败从而影响价值估计。比如在 TD3 或 SAC 里如果环境因为最大步数限制而结束但你把它当成 terminated智能体会学到错误的价值函数认为所有轨迹都失败了正确做法是让算法在truncated时做 bootstrap而不是直接清零。迁移后这部分逻辑一定要检查清楚。2.2 spaces 模块的差异与类型检查gym.spaces和gymnasium.spaces表面上一一对应实际上有一些细小的行为差异。最典型的是gymnasium.spaces.Box在底层会做更严格的类型检查。老 Gym 中Box的low和high会尝试转换为np.float32而 Gymnasium 中如果传入的shape与low/high的 shape 不一致会直接报错而不是静默广播。这个改变对于老环境来说尤其隐蔽因为你可能依赖了之前隐式广播的行为。我在迁移一个自研的机械臂环境时就踩过这个坑。原来的observation_space定义是self.observation_space spaces.Box(low-1, high1, shape(6,))这里low和high是标量shape是(6,)在 Gym 里能正常工作。但在 Gymnasium 下如果你直接这样用会收到一个警告提示Box的low/high形状为()与shape形状为(6,)不匹配。虽然现在还是警告而非错误但官方已经在规划未来版本直接报错。把所有相关代码改成显式数组self.observation_space spaces.Box(low-1.0, high1.0, shape(6,), dtypenp.float32)除了 Box 外spaces.Dict和spaces.Tuple在 Gymnasium 中的实现也更规范与spaces的类型标注、嵌套结构检查都更严格。迁移时建议直接在环境类里加一个简单的自检方法用gymnasium.utils.env_checker.check_env来验证环境定义是否符合规范。这个方法比 Gym 时代的类似工具更全面能检查出不少隐藏问题。2.3 Wrappers 的替换与自定义 Wrapper 适配Gym 时代的 Wrapper 体系在 Gymnasium 里基本保留下来了但类的命名空间和部分 API 有变化。最常见的替换清单如下老 Gym 写法Gymnasium 写法gym.wrappers.TimeLimitgymnasium.wrappers.TimeLimitgym.wrappers.RescaleActiongymnasium.wrappers.RescaleActiongym.wrappers.FlattenObservationgymnasium.wrappers.FlattenObservationgym.wrappers.RecordEpisodeStatisticsgymnasium.wrappers.RecordEpisodeStatisticsgym.wrappers.TransformObservationgymnasium.wrappers.TransformObservationgym.wrappers.RecordVideogymnasium.wrappers.RecordVideo大部分 Wrapper 的用法基本不变比如import gymnasium as gym from gymnasium.wrappers import RescaleAction, FlattenObservation env gym.make(MyEnv-v0, render_modergb_array) env RescaleAction(env, min_action-1.0, max_action1.0) env FlattenObservation(env)但自定义 Wrapper 需要特别注意一个点老 Gym 的Wrapper.__init__里会调用self.env env这在 Gymnasium 里也保留但Wrapper基类的属性访问逻辑做了调整。如果你在自定义 Wrapper 中重写了observation_space属性必须确保赋值的是一个gymnasium.spaces.Space对象不能是字典或元组。这在老代码里很常见尤其是那些为了快速拼装观测而把多个传感器数据直接塞进 dict 的环境。还有一个常见的坑是RecordVideo的video_folder参数。老 Gym 中如果传video_folderNone会默认使用/tmp或当前目录Gymnasium 中同样支持但如果视频记录器在初始化时无法创建目录会抛异常。训练服务器上如果只读文件系统跑某个组件这就会炸。所以迁移后建议手动指定一个可写的video_folder。2.4 make 与 env 注册机制的差异Gymnasium 的make机制整体沿用了 Gym 的设计但内部实现更干净。最核心的变化是gymnasium.register与entry_point的用法基本一致但注册环境时多了一些可选参数比如order_enforce和disable_env_checker。这些参数直接控制make创建环境后是否强制执行接口检查。在实际迁移中gymnasium.make有个行为和 Gym 不同默认会启用EnvChecker也就是创建环境后自动跑一遍接口检查。如果环境类里某个该方法签名不标准比如reset没有关键字参数make时会直接抛异常而不是像老 Gym 那样让你跑起来才报错。这个改变对迁移是好事因为问题暴露得更早但对那些只改了导入路径、其他一概没动的老环境来说可能第一次跑就崩。这种情况下有两个选择一是把你自定义环境改到完全合规推荐二是在make时传入disable_env_checkerTrue跳过检查但只适合临时测试不建议上线。注册这块的兼容写法from gymnasium.envs.registration import register register( idMyEnv-v0, entry_pointmy_module.envs:MyEnv, max_episode_steps500, )注册逻辑放在包的__init__.py里这样导入包时环境自动注册使用方式和之前一致。3. 实操过程与核心环节实现3.1 环境准备与依赖替换在动手改代码前先把依赖环境理干净。我推荐的做法是新建一个虚拟环境然后直接安装gymnasium同时按需安装gymnasium[all]或只装核心依赖。python -m venv .venv-gymnasium source .venv-gymnasium/bin/activate pip install gymnasium[all]如果你原来的项目里还有gym建议先卸载避免出现两个包并存引起的混乱。关于是否需要兼容老 Gym我的经验是不要硬兼容。因为gym和gymnasium在 Python 层面都叫gym的模块名你不能同时 import 两个库如果用import gymnasium as gym则老代码里散落的gym调用能跑通但这也意味着老gym相关的源码逻辑无法访问。所以干脆一步到位卸载gym全部代码显式改为import gymnasium as gym。对于有requirements.txt的项目把老 Gym 替换为gymnasium0.29如果有用到环境渲染或者 Atari、Box2D 等环境套件需要额外装gymnasium[atari]、gymnasium[box2d]等。注意gymnasium[box2d]依赖的Box2D库在 Python 3.12 上可能出现编译问题建议直接装swig后重试或者有条件的话使用预编译 wheel。3.2 环境代码迁移实例从旧接口到新接口用一个具体的例子来走一遍。假设原来自定义环境的长这样import gym from gym import spaces import numpy as np class GridWorldEnv(gym.Env): metadata {render.modes: [human]} def __init__(self, grid_size5): super().__init__() self.grid_size grid_size self.observation_space spaces.Discrete(grid_size * grid_size) self.action_space spaces.Discrete(4) self.state None def seed(self, seedNone): self.np_random, seed gym.utils.seeding.np_random(seed) return [seed] def reset(self): self.state 0 return self.state def step(self, action): # 动作: 0up, 1down, 2left, 3right if action 0: self.state min(self.state self.grid_size, self.grid_size * self.grid_size - 1) elif action 1: self.state max(self.state - self.grid_size, 0) elif action 2: self.state max(self.state - 1, 0) elif action 3: self.state min(self.state 1, self.grid_size * self.grid_size - 1) done self.state self.grid_size * self.grid_size - 1 reward 1.0 if done else 0.0 return self.state, reward, done, {} def render(self, modehuman): print(fCurrent state: {self.state})迁移到 Gymnasium 后import gymnasium as gym from gymnasium import spaces import numpy as np class GridWorldEnv(gym.Env): metadata {render_modes: [human], render_fps: 30} def __init__(self, grid_size5, render_modeNone): super().__init__() self.grid_size grid_size self.observation_space spaces.Discrete(grid_size * grid_size) self.action_space spaces.Discrete(4) self.state None self.render_mode render_mode self.window None def reset(self, *, seedNone, optionsNone): super().reset(seedseed) self.state 0 return self.state, {} def step(self, action): if action 0: self.state min(self.state self.grid_size, self.grid_size * self.grid_size - 1) elif action 1: self.state max(self.state - self.grid_size, 0) elif action 2: self.state max(self.state - 1, 0) elif action 3: self.state min(self.state 1, self.grid_size * self.grid_size - 1) terminated self.state self.grid_size * self.grid_size - 1 truncated False reward 1.0 if terminated else 0.0 info {} return self.state, reward, terminated, truncated, info def render(self): if self.render_mode human: print(fCurrent state: {self.state})改动点一目了然删掉了自定义seed方法改用reset的seed参数。reset的返回值从单一 obs 变成(obs, info)元组。step返回值从四元组变成五元组。render不再接收mode参数而是读取构造时传入的render_mode。这其中的关键在于super().reset(seedseed)这一行。如果不调用它环境内的np_random不会被初始化后面如果用到self.np_random生成随机数就会报错。3.3 训练脚本的迁移接入 Gymnasium 核心 API环境迁移完了训练脚本也要跟着改。最关键的是env gym.make(...)调用和算法内部对done标志的处理。一个典型的 DQN 训练循环原来可能是这样done False obs env.reset() while not done: action policy(obs) obs, reward, done, info env.step(action) replay_buffer.add(obs, action, reward, done)迁移后需要改成terminated, truncated False, False obs, _ env.reset() while not (terminated or truncated): action policy(obs) obs, reward, terminated, truncated, info env.step(action) done terminated or truncated replay_buffer.add(obs, action, reward, done, truncated)注意这里的truncated也需要单独传给回放缓冲区或者至少让算法知道这两个标志的差异。如果算法只接收一个布尔值那么在truncated为 True 时应该把done设为 False因为这不是真实的终止状态而只是达到步数上限。但这取决于具体算法DQN 里习惯把done设为terminated在计算 target 时如果truncatedTrue则不应把 Q 值清零而应该继续用下一个状态的 Q 值做 bootstrap。这个细节直接决定了训练是否收敛。更通用一点可以直接写一个小的辅助函数def step_env(env, action): obs, reward, terminated, truncated, info env.step(action) done terminated or truncated return obs, reward, done, terminated, truncated, info这样上层算法代码可以先通过done判断是否结束循环再通过terminated和truncated决定具体的学习逻辑改动最小。3.4 兼容层实现让老代码无缝运行如果你的项目太大短期没法把所有模块改完也可以做一个兼容层把gym重定向到gymnasium。在项目根目录放一个gym_compat.pyimport gymnasium as gym import gymnasium.spaces as spaces from gymnasium import Env, Wrapper from gymnasium import register, make __all__ [gym, spaces, Env, Wrapper, register, make]然后在需要兼容的地方import gym_compat as gym或者更粗暴一点直接把gym模块替换import sys import gymnasium sys.modules[gym] gymnasium但这种方法非常危险比如某些库会同时依赖gym的真实 API 内部属性直接替换会导致深层调用出错。我建议只在迫不得已时用而且只用于跑通流程最终还是要逐步替换成显式import gymnasium。如果一定要做这套兼容层还有个常见需求是环境注册入口。老 Gym 用户可能习惯了用gym.envs.registration.register注册环境而 Gymnasium 注册入口变成了gymnasium.envs.registration.register。兼容层里可以顺手做一个别名from gymnasium.envs.registration import register as gym_register然后统一走一套注册函数降低散落的注册入口带来的维护成本。3.5 自动化辅助迁移脚本与代码扫描迁移工作量大时靠手工改太容易漏。我写过一个简单的脚本用来扫描代码库中的 Gym API 调用点并给出替换建议。核心思路就是正则匹配和 AST 分析。用 AST 会更可靠因为能正确解析出函数调用的具体位置和参数结构。模板如下import ast import sys class GymAPIVisitor(ast.NodeVisitor): def __init__(self): self.hits [] def visit_Attribute(self, node): if isinstance(node.value, ast.Name) and node.value.id gym: self.hits.append((node.attr, node.lineno)) self.generic_visit(node) def visit_Call(self, node): if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name): if node.func.value.id gym: self.hits.append((fcall:{node.func.attr}, node.lineno)) self.generic_visit(node) with open(sys.argv[1], r) as f: tree ast.parse(f.read()) visitor GymAPIVisitor() visitor.visit(tree) for attr, lineno in visitor.hits: print(f{lineno}: gym.{attr})这个脚本不会自动改代码但能快速找出所有潜在改动点。结合git diff做逐文件核对效率比纯靠眼睛高很多。对于 step 返回值处理的自动化改法可以用正则做粗替换但这类改动必须有测试兜底否则很容易误伤。我个人的建议是自动化工具只用来定位问题实际改写还是要人工判断尤其是done到terminated/truncated的语义拆分机器无法自动理解业务逻辑。4. 常见问题与排查技巧实录4.1 常见报错与解决方案速查表报错信息原因解决方案AttributeError: module gymnasium has no attribute core混用了 Gym 和 Gymnasium 的 API 引用统一import gymnasium as gym避免直接访问gym.coreTypeError: reset() got an unexpected keyword argument seed环境类没有把seed定义为关键字参数改写reset(self, *, seedNone, optionsNone)并调用super().reset(seedseed)ValueError: Buffer dtype mismatchBox空间 dtype 不匹配显式指定dtypenp.float32并检查传入观测的 dtypeRuntimeError: An environmentsreset()method must return (obs, info)环境reset返回值格式不符合新 API返回(obs, info)而不是obsgymnasium.error.InvalidAction: action must be a numpy arrayDiscrete空间的动作类型要求严格把动作转换为np.int64或np.int32NameError: name gym is not defined老代码仍直接import gym但环境中没有安装gym改为import gymnasium as gym4.2 关于truncated标志的语义陷阱这个算是我迁移过程中遇到的最复杂的逻辑问题。很多老代码里根本没有truncated这个概念所有结束都用一个done表示。迁移后如果简单地用terminated or truncated来填充done对某些算法是对的对某些算法是错的。具体来说DQN 系列的算法通常会把done当作“是否不进行下一步 bootstrap”的标志所以truncated和terminated对它们的影响是一样的用or合并没问题。但像基于 TD 的连续控制算法DDPG、TD3、SAC里如果truncated被当作结束标志会导致目标 Q 值被直接当 0训练出来的值函数会系统性偏低。也就是说如果任务本身没有真正的失败状态只是步数超限正确的做法是done terminated # 不能把 truncated 混进去我建议在回放缓冲区里把terminated和truncated分开存储或者在info里单独记录TimeLimit.truncated标志这样后续做任何算法实验时可以灵活切换。很多开源库比如 Stable-Baselines3已经这么做了但自研项目里容易被忽视。4.3 Render 相关的兼容性问题渲染这块也是迁移时的高发问题区。老代码里常见的写法env gym.make(MyEnv-v0) env.render(modehuman)Gymnasium 下要写成env gym.make(MyEnv-v0, render_modehuman) env.render()原因在于render_mode必须在构造环境时确定因为底层渲染器的生命周期是绑定在环境实例上的。如果你在make之后动态切换渲染模式很多时候不会报错但实际的渲染行为可能不符合预期比如human模式可能没有真正把画面推送到窗口。另外Gymnasium 的render_mode可选值更规范包括human、rgb_array、ansi、single_rgb_array等。如果自定义环境里实现了自己的render需要根据render_mode分别返回不同的内容。比如human模式返回 None 或直接往窗口绘制rgb_array模式返回(H, W, 3)的 uint8 数组。这些细节在 Gym 时代没有强制但在 Gymnasium 里是会被env_checker验证的。4.4 环境检查器 env_checker 的使用与误报处理Gymnasium 提供了一个非常好用的工具from gymnasium.utils.env_checker import check_env env MyEnv() check_env(env)它会对环境的观测空间、动作空间、步进逻辑、reset 逻辑、渲染接口做全面检查。这个在迁移过程中可以帮你快速定位问题尤其是那些隐藏的“非标准行为”。但也要注意这个检查器偶尔会出现误报特别是当你故意使用了某些非常规但合理的环境设计时。比如动作空间是spaces.Dict但内部只支持特定组合的字典键检查器会遍历所有可能的组合然后报一个InvalidAction但这可能是你故意设置的约束。这种情况下合理的做法是被迫在make时传入disable_env_checkerTrue或者通过 Wrapper 做一层转换把 Dict 动作映射到真正的合法空间。4.5 记录 Episode 统计信息时的 API 变化另一个常见迁移问题在RecordEpisodeStatistics的返回值上。老 Gym 里这个 Wrapper 会把统计信息写入info[episode]字典中包含r和l两个键。Gymnasium 基本保留了这套用法但键名可能有所不同。如果你依赖info[episode][r]来提取奖励建议迁移后先跑一个简单环境验证一下 key 是否存在避免训练时取不到值导致隐性 bug。有种更稳妥的替代方案是自己实现一个统计 Wrapper不依赖内部键名并在每个 episode 结束时把episode_reward和episode_length显式写进info。这样无论底层库怎么变你的上层代码不会受影响。示例class EpisodeStatsWrapper(gym.Wrapper): def __init__(self, env): super().__init__(env) self.episode_reward 0.0 self.episode_length 0 self.episode_count 0 def reset(self, **kwargs): obs, info self.env.reset(**kwargs) self.episode_reward 0.0 self.episode_length 0 return obs, info def step(self, action): obs, reward, terminated, truncated, info self.env.step(action) self.episode_reward reward self.episode_length 1 if terminated or truncated: self.episode_count 1 info[episode] { r: self.episode_reward, l: self.episode_length, count: self.episode_count, } return obs, reward, terminated, truncated, info4.6 多环境并行与向量化接口的差异如果你的项目里用了gym.vector.AsyncVectorEnv或gym.vector.SyncVectorEnv迁移时也要格外留意。Gymnasium 提供了gymnasium.vector但内部实现和 API 有差异。老写法from gym.vector import AsyncVectorEnv envs AsyncVectorEnv([lambda: gym.make(MyEnv-v0) for _ in range(4)])迁移后from gymnasium.vector import AsyncVectorEnv envs AsyncVectorEnv([lambda: gym.make(MyEnv-v0) for _ in range(4)])看着像是只改了导入路径但如果子环境内部使用了 Gymnasium 规范vector的reset返回也是一个(obs, info)元组obs是一个堆叠后的批量观测。另外AsyncVectorEnv的共享内存类型检查更严格如果观测不是np.ndarray或无法转换启动时会直接报错。所以迁移后多环境并行这块也要单独跑一下。5. 工具选型与迁移策略建议5.1 第三方库的兼容现状迁移过程中你依赖的强化学习库大概率也已经切到了 Gymnasium。比如 Stable-Baselines3 从 2.0 开始就完全基于 Gymnasium老版本会提示你必须用gymnasium作为环境后端。如果你的项目依赖了 RLlib、Sample Factory 或老版baselines它们的 Gymnasium 适配程度各不相同必须提前调研清楚。我当时的项目虽然是自研算法但用了tensorboard做日志、optuna做超参搜索、imitation做行为克隆。其中imitation在新版本里已经支持 Gymnasium但如果你锁的是老版本环境类型检查可能过不去。解决方案是把这些中间库的版本全部升级到与 Gymnasium 兼容的版本同时留意它们的requirements.txt是否锁定老 Gym避免在安装时又把 Gym 装回来。5.2 一步到位还是逐步灰度这个问题没有标准答案取决于你的代码规模和风险承受能力。我的建议是分三步走第一步建立起独立的 Gymnasium 测试环境把自定义环境迁移过去跑通env_checker并复现一次随机策略交互确认底层环境没问题。第二步把算法核心的训练循环迁移过去保持自定义环境不变如果还没迁完用gymnasium.make包装原有环境作为临时兼容观察训练曲线是否与老版本对齐。第三步清理所有兼容代码删除gym引用统一为gymnasium跑全量回归测试。这种灰度迁移的好处是你可以随时定位问题范围训练曲线不对是环境的问题还是算法的问题通过分步切换可以很清楚地回答。5.3 代码改造之外别忘了文档和实验记录技术细节之外还有一件容易忽略的事迁移后实验记录的连续性。如果你有一批基于老 Gym 跑出来的基线实验结果迁移后环境行为可能因为随机种子、空间 dtype、截断语义等变化而产生微小的不一致。虽然这些不一致通常不会改变策略方向但在对比实验结果时建议在实验记录里标注“Gymnasium 迁移后”的版本号避免后续做实验对比时产生歧义。我当时把所有迁移相关的 commit 单独打了一个 tag比如migration-gymnasium-0.29并在 README 里更新了环境依赖说明和已知差异。这套做法在团队协作时尤其重要因为你不想让队友在一个混合了新旧 API 的代码库上做开发。6. 最后的实操心得这一次迁移做下来我最大的一个体会是import gymnasium as gym只是表面功夫真正的迁移难点在于done标志的语义拆分以及环境接口的规范性。如果你原来写的环境本身就严格遵循 Gym 官方规范比如所有动作和观测都有明确的Space声明reset和step签名标准那么迁移到 Gymnasium 基本就是改两个方法签名的事。但如果你以前写过不少“野路子”环境——比如直接返回dict而不是Space声明的观测、或者把done和truncated混着用——那迁移的工程量可能会比预想的大不少。另外也别小看super().reset(seedseed)这一行。很多自研环境在迁移后训练结果无法复现问题就出在这里。还有一点就是不要为了省事而直接跳过env_checker它能在五分钟内帮你把隐藏的接口问题全部揪出来省下后面几天排查的功夫。如果团队里有人对这次迁移有顾虑我通常会给一个简单的定心丸Gymnasium 的前身就是 GymAPI 的兼容性保留了八成以上真正需要动脑子的地方只有 step 返回值里新增的两个布尔值。只要你理解terminated和truncated的语义区别其他几乎都是机械式的替换工作。而且迁移完成后你会发现代码更规范了跑在新 Python 版本上也不会因为 Gym 的停更而提心吊胆。本文还有配套的精品资源点击获取
Gymnasium迁移实战：从OpenAI Gym平滑升级强化学习环境
简介本资源是面向强化学习开发者与研究者的Gymnasium迁移实践指南专为熟悉OpenAI Gym但需平滑过渡至新标准框架的Python工程师设计解决API变更、环境重构与项目适配等核心迁移难题。压缩包共301个文件1.81MB含187个Python源码文件覆盖环境封装、空间定义、向量化接口等关键模块、82张PNG图像含架构图与流程示意图、12个XML配置及Dockerfile、docker_entrypoint等容器化部署文件以及CONTRIBUTING.md、LICENSE.md、PULL_REQUEST_TEMPLATE.md等工程规范文档。已有421人学习下载资源结构完整呈现Gymnasium官方维护的代码组织逻辑与迁移路径既包含可直接复用的替代实现也提供从Gym API到Gymnasium v0.27的逐层转换说明、测试验证脚本和典型环境重写范例助力用户快速掌握新版设计哲学并完成存量项目升级。 Gymnasium 这个名字这两年只要玩强化学习的基本都绕不开。如果你打开一个老项目发现里面还是import gym然后跑起来报了一堆环境注册的警告甚至直接崩溃那你大概率正面临一次从 OpenAI Gym 到 Gymnasium 的迁移。这个迁移不是简单的换一个 pip 包名它涉及环境接口签名、Wrappers 机制、Space 类型检查、以及底层向量化实现等一系列改动。我最近把几个线上用的强化学习训练脚本从 Gym 迁到了 Gymnasium顺手把一套基于 Gym 接口封装的自研环境也改过来了整个过程踩了不少坑也沉淀了一些可复用的替换思路。这篇文章就把这次迁移的完整方案拆开讲清楚重点说说源码层面怎么改、API 差异背后的设计意图、以及如何用一套替代方案平滑过渡不中断现有训练流程。1. 内容整体设计与思路拆解1.1 为什么必须迁Gym 停更与 API 分裂的必然性先交代一下背景。OpenAI Gym 在强化学习领域的历史地位不用多说但它实际上在 2021 年前后就基本停止了积极维护后由 Farama Foundation 接手并改名为 Gymnasium。这个接过接力棒的项目不只是换个名字而是把原来 Gym 里很多悬而未决的设计问题一并解决掉。最直接的影响就是老 Gym 的 API 在0.26版本里引入了新的 step 接口返回五元组但这套新接口和早期的四元组接口并存了很久导致大量开源代码和自研代码要么基于旧接口写要么在不同版本之间打架。而 Gymnasium 直接统一为五元组并把 reset 接口的签名也规范了等于把这段历史债务一次性切掉。从实际项目维护的角度看不迁移的代价会随着时间增长越来越大。一方面Gym 的 PyPI 包已经停止更新依赖它的项目在 Python 新版本环境下会出现兼容性问题比如distutils的移除就直接让 Gym 在 Python 3.12 上安装失败。另一方面社区生态的重心已经完全转移到 Gymnasium 上最新的强化学习库、Rendering 工具、环境集合都以它为基准。如果只守着老代码新算法接不进来新环境用不了慢慢就变成一座孤岛。所以迁移不是赶时髦而是现实倒逼。1.2 替代方案的整体设计思路兼容层 增量改造我做迁移时定的原则不是“推倒重来”而是“兼容层 增量改造”。所谓兼容层就是在不改变原有训练脚本调用方式的前提下把底层环境库和 Gymnasium 的接口对齐。具体做到两层自定义环境类仍然通过gymnasium.Env继承但对外暴露的方法名、参数顺序尽量与老 Gym 保持一致减少上层策略代码的改动面。训练脚本里统一通过gymnasium.make注册和创建环境不再直接gym.make。如果需要兼容老代码里残留的gym.make调用就做一个轻量级的别名模块把gym重定向到gymnasium。对应到源码层面会有一份改动清单env.seed()改为env.reset(seed...)env.step()的返回值从四元组改为五元组注意接收terminated和truncated这两个布尔值env.render()的调用方式从env.render(modehuman)改为env.render()配合构造时的render_mode参数observation_space和action_space从gym.spaces改成gymnasium.spaces类型声明和抽样行为也有细微差别。这套设计的优势在于训练代码、算法代码、评估代码三个层面可以分步改造每完成一步就回归测试不会出现一次迁移就要把所有代码全部改完、牵一发动全身的局面。而且由于 Gymnasium 本身保持了相当比例的老接口兼容性比如gymnasium.make的用法基本迁移过来就能跑实际迁移成本比想象中低不少。1.3 迁移前必须做好的资源盘点迁移前先盘点手里的代码资产这一步省不得。建议列一个清单把项目里所有直接或间接依赖 Gym 的模块找出来包括直接import gym的模块、通过gym.make创建环境的脚本、注册了自定义环境的包、使用了gym.spaces的观测和动作定义、依赖gym.Wrapper的封装层、以及引用了gym.utils.seeding等工具函数的代码。我当时用一个简单的 grep 命令先扫一遍grep -rn import gym\|from gym --include*.py | grep -v .venv | grep -v .git再把结果按模块分组估计每个文件的改动量。这一步的意义在于避免迁移到一半才发现某个深层依赖没考虑到比如一个 Wrapper 里偷偷用了env.unwrapped的某种老行为或者在某个角落直接调用了gym.logger。这些隐藏依赖在迁移前往往不会被注意到但在切换之后就会变成难以排查的坑。另外别忘了检查环境中是否存在多个 Gym 版本混用的情况。比如主环境装了gymnasium但某个子模块的 venv 里还锁定着一个老版gym。这类版本冲突比 API 改写更隐蔽因为它可能只在特定路径下被触发。我建议在迁移期间把所有虚拟环境统一重建并把 Gym 相关依赖固定为 Gymnasium 之后跑一遍全量测试避免新旧两套库交错调用。2. 核心细节解析与实操要点2.1 从 gym.Env 到 gymnasium.Env继承方式与接口变化先说最底层的环境类。老 Gym 的环境类定义长这样import gym from gym import spaces class MyEnv(gym.Env): def __init__(self): self.action_space spaces.Discrete(2) self.observation_space spaces.Box(low0, high1, shape(4,))同样的类在 Gymnasium 下需要改成import gymnasium as gym from gymnasium import spaces class MyEnv(gym.Env): def __init__(self, render_modeNone): self.action_space spaces.Discrete(2) self.observation_space spaces.Box(low0, high1, shape(4,)) self.render_mode render_mode一眼看上去改动不大但有几个关键点需要特别留意。第一个是metadata里的render_modes字段。Gymnasium 的环境类通常需要在类级别定义这个字段否则在构造时传render_mode会触发警告虽然不会直接报错但属于不规范行为。具体定义方式class MyEnv(gym.Env): metadata {render_modes: [human, rgb_array], render_fps: 30}第二个是reset方法的签名。老 Gym 的reset通常没有参数或者接受一个可选的seed。Gymnasium 的规范是def reset(self, *, seedNone, optionsNone): super().reset(seedseed) # 初始化状态 self.state ... info {} return self._get_obs(), info这里有两个细节。一是seed和options都是强制关键字参数不能写成位置参数二是必须调用super().reset(seedseed)来重置父类内部的状态包括np_random。如果漏掉这行环境虽然能跑但是随机种子永远不会生效实验结果无法复现。这个坑很隐蔽因为老 Gym 里很多环境根本不调用super().reset()迁移后不补上就会出问题。第三个是step方法的返回值。老 Gym 0.25 及之前的版本返回(obs, reward, done, info)四元组0.26 引入了五元组但需要额外传new_step_apiTrueGymnasium 直接统一为五元组def step(self, action): # 执行动作更新状态 terminated ... truncated ... reward ... info {} return self._get_obs(), reward, terminated, truncated, infoterminated表示任务是否因达成目标或进入终端状态而结束truncated表示是否因超过步数上限、超出边界等外部条件而强制截断。这两者的语义区别很重要尤其是在处理稀疏奖励任务时如果算法分不清这两个布尔值timeout 会被错误地当成任务失败从而影响价值估计。比如在 TD3 或 SAC 里如果环境因为最大步数限制而结束但你把它当成 terminated智能体会学到错误的价值函数认为所有轨迹都失败了正确做法是让算法在truncated时做 bootstrap而不是直接清零。迁移后这部分逻辑一定要检查清楚。2.2 spaces 模块的差异与类型检查gym.spaces和gymnasium.spaces表面上一一对应实际上有一些细小的行为差异。最典型的是gymnasium.spaces.Box在底层会做更严格的类型检查。老 Gym 中Box的low和high会尝试转换为np.float32而 Gymnasium 中如果传入的shape与low/high的 shape 不一致会直接报错而不是静默广播。这个改变对于老环境来说尤其隐蔽因为你可能依赖了之前隐式广播的行为。我在迁移一个自研的机械臂环境时就踩过这个坑。原来的observation_space定义是self.observation_space spaces.Box(low-1, high1, shape(6,))这里low和high是标量shape是(6,)在 Gym 里能正常工作。但在 Gymnasium 下如果你直接这样用会收到一个警告提示Box的low/high形状为()与shape形状为(6,)不匹配。虽然现在还是警告而非错误但官方已经在规划未来版本直接报错。把所有相关代码改成显式数组self.observation_space spaces.Box(low-1.0, high1.0, shape(6,), dtypenp.float32)除了 Box 外spaces.Dict和spaces.Tuple在 Gymnasium 中的实现也更规范与spaces的类型标注、嵌套结构检查都更严格。迁移时建议直接在环境类里加一个简单的自检方法用gymnasium.utils.env_checker.check_env来验证环境定义是否符合规范。这个方法比 Gym 时代的类似工具更全面能检查出不少隐藏问题。2.3 Wrappers 的替换与自定义 Wrapper 适配Gym 时代的 Wrapper 体系在 Gymnasium 里基本保留下来了但类的命名空间和部分 API 有变化。最常见的替换清单如下老 Gym 写法Gymnasium 写法gym.wrappers.TimeLimitgymnasium.wrappers.TimeLimitgym.wrappers.RescaleActiongymnasium.wrappers.RescaleActiongym.wrappers.FlattenObservationgymnasium.wrappers.FlattenObservationgym.wrappers.RecordEpisodeStatisticsgymnasium.wrappers.RecordEpisodeStatisticsgym.wrappers.TransformObservationgymnasium.wrappers.TransformObservationgym.wrappers.RecordVideogymnasium.wrappers.RecordVideo大部分 Wrapper 的用法基本不变比如import gymnasium as gym from gymnasium.wrappers import RescaleAction, FlattenObservation env gym.make(MyEnv-v0, render_modergb_array) env RescaleAction(env, min_action-1.0, max_action1.0) env FlattenObservation(env)但自定义 Wrapper 需要特别注意一个点老 Gym 的Wrapper.__init__里会调用self.env env这在 Gymnasium 里也保留但Wrapper基类的属性访问逻辑做了调整。如果你在自定义 Wrapper 中重写了observation_space属性必须确保赋值的是一个gymnasium.spaces.Space对象不能是字典或元组。这在老代码里很常见尤其是那些为了快速拼装观测而把多个传感器数据直接塞进 dict 的环境。还有一个常见的坑是RecordVideo的video_folder参数。老 Gym 中如果传video_folderNone会默认使用/tmp或当前目录Gymnasium 中同样支持但如果视频记录器在初始化时无法创建目录会抛异常。训练服务器上如果只读文件系统跑某个组件这就会炸。所以迁移后建议手动指定一个可写的video_folder。2.4 make 与 env 注册机制的差异Gymnasium 的make机制整体沿用了 Gym 的设计但内部实现更干净。最核心的变化是gymnasium.register与entry_point的用法基本一致但注册环境时多了一些可选参数比如order_enforce和disable_env_checker。这些参数直接控制make创建环境后是否强制执行接口检查。在实际迁移中gymnasium.make有个行为和 Gym 不同默认会启用EnvChecker也就是创建环境后自动跑一遍接口检查。如果环境类里某个该方法签名不标准比如reset没有关键字参数make时会直接抛异常而不是像老 Gym 那样让你跑起来才报错。这个改变对迁移是好事因为问题暴露得更早但对那些只改了导入路径、其他一概没动的老环境来说可能第一次跑就崩。这种情况下有两个选择一是把你自定义环境改到完全合规推荐二是在make时传入disable_env_checkerTrue跳过检查但只适合临时测试不建议上线。注册这块的兼容写法from gymnasium.envs.registration import register register( idMyEnv-v0, entry_pointmy_module.envs:MyEnv, max_episode_steps500, )注册逻辑放在包的__init__.py里这样导入包时环境自动注册使用方式和之前一致。3. 实操过程与核心环节实现3.1 环境准备与依赖替换在动手改代码前先把依赖环境理干净。我推荐的做法是新建一个虚拟环境然后直接安装gymnasium同时按需安装gymnasium[all]或只装核心依赖。python -m venv .venv-gymnasium source .venv-gymnasium/bin/activate pip install gymnasium[all]如果你原来的项目里还有gym建议先卸载避免出现两个包并存引起的混乱。关于是否需要兼容老 Gym我的经验是不要硬兼容。因为gym和gymnasium在 Python 层面都叫gym的模块名你不能同时 import 两个库如果用import gymnasium as gym则老代码里散落的gym调用能跑通但这也意味着老gym相关的源码逻辑无法访问。所以干脆一步到位卸载gym全部代码显式改为import gymnasium as gym。对于有requirements.txt的项目把老 Gym 替换为gymnasium0.29如果有用到环境渲染或者 Atari、Box2D 等环境套件需要额外装gymnasium[atari]、gymnasium[box2d]等。注意gymnasium[box2d]依赖的Box2D库在 Python 3.12 上可能出现编译问题建议直接装swig后重试或者有条件的话使用预编译 wheel。3.2 环境代码迁移实例从旧接口到新接口用一个具体的例子来走一遍。假设原来自定义环境的长这样import gym from gym import spaces import numpy as np class GridWorldEnv(gym.Env): metadata {render.modes: [human]} def __init__(self, grid_size5): super().__init__() self.grid_size grid_size self.observation_space spaces.Discrete(grid_size * grid_size) self.action_space spaces.Discrete(4) self.state None def seed(self, seedNone): self.np_random, seed gym.utils.seeding.np_random(seed) return [seed] def reset(self): self.state 0 return self.state def step(self, action): # 动作: 0up, 1down, 2left, 3right if action 0: self.state min(self.state self.grid_size, self.grid_size * self.grid_size - 1) elif action 1: self.state max(self.state - self.grid_size, 0) elif action 2: self.state max(self.state - 1, 0) elif action 3: self.state min(self.state 1, self.grid_size * self.grid_size - 1) done self.state self.grid_size * self.grid_size - 1 reward 1.0 if done else 0.0 return self.state, reward, done, {} def render(self, modehuman): print(fCurrent state: {self.state})迁移到 Gymnasium 后import gymnasium as gym from gymnasium import spaces import numpy as np class GridWorldEnv(gym.Env): metadata {render_modes: [human], render_fps: 30} def __init__(self, grid_size5, render_modeNone): super().__init__() self.grid_size grid_size self.observation_space spaces.Discrete(grid_size * grid_size) self.action_space spaces.Discrete(4) self.state None self.render_mode render_mode self.window None def reset(self, *, seedNone, optionsNone): super().reset(seedseed) self.state 0 return self.state, {} def step(self, action): if action 0: self.state min(self.state self.grid_size, self.grid_size * self.grid_size - 1) elif action 1: self.state max(self.state - self.grid_size, 0) elif action 2: self.state max(self.state - 1, 0) elif action 3: self.state min(self.state 1, self.grid_size * self.grid_size - 1) terminated self.state self.grid_size * self.grid_size - 1 truncated False reward 1.0 if terminated else 0.0 info {} return self.state, reward, terminated, truncated, info def render(self): if self.render_mode human: print(fCurrent state: {self.state})改动点一目了然删掉了自定义seed方法改用reset的seed参数。reset的返回值从单一 obs 变成(obs, info)元组。step返回值从四元组变成五元组。render不再接收mode参数而是读取构造时传入的render_mode。这其中的关键在于super().reset(seedseed)这一行。如果不调用它环境内的np_random不会被初始化后面如果用到self.np_random生成随机数就会报错。3.3 训练脚本的迁移接入 Gymnasium 核心 API环境迁移完了训练脚本也要跟着改。最关键的是env gym.make(...)调用和算法内部对done标志的处理。一个典型的 DQN 训练循环原来可能是这样done False obs env.reset() while not done: action policy(obs) obs, reward, done, info env.step(action) replay_buffer.add(obs, action, reward, done)迁移后需要改成terminated, truncated False, False obs, _ env.reset() while not (terminated or truncated): action policy(obs) obs, reward, terminated, truncated, info env.step(action) done terminated or truncated replay_buffer.add(obs, action, reward, done, truncated)注意这里的truncated也需要单独传给回放缓冲区或者至少让算法知道这两个标志的差异。如果算法只接收一个布尔值那么在truncated为 True 时应该把done设为 False因为这不是真实的终止状态而只是达到步数上限。但这取决于具体算法DQN 里习惯把done设为terminated在计算 target 时如果truncatedTrue则不应把 Q 值清零而应该继续用下一个状态的 Q 值做 bootstrap。这个细节直接决定了训练是否收敛。更通用一点可以直接写一个小的辅助函数def step_env(env, action): obs, reward, terminated, truncated, info env.step(action) done terminated or truncated return obs, reward, done, terminated, truncated, info这样上层算法代码可以先通过done判断是否结束循环再通过terminated和truncated决定具体的学习逻辑改动最小。3.4 兼容层实现让老代码无缝运行如果你的项目太大短期没法把所有模块改完也可以做一个兼容层把gym重定向到gymnasium。在项目根目录放一个gym_compat.pyimport gymnasium as gym import gymnasium.spaces as spaces from gymnasium import Env, Wrapper from gymnasium import register, make __all__ [gym, spaces, Env, Wrapper, register, make]然后在需要兼容的地方import gym_compat as gym或者更粗暴一点直接把gym模块替换import sys import gymnasium sys.modules[gym] gymnasium但这种方法非常危险比如某些库会同时依赖gym的真实 API 内部属性直接替换会导致深层调用出错。我建议只在迫不得已时用而且只用于跑通流程最终还是要逐步替换成显式import gymnasium。如果一定要做这套兼容层还有个常见需求是环境注册入口。老 Gym 用户可能习惯了用gym.envs.registration.register注册环境而 Gymnasium 注册入口变成了gymnasium.envs.registration.register。兼容层里可以顺手做一个别名from gymnasium.envs.registration import register as gym_register然后统一走一套注册函数降低散落的注册入口带来的维护成本。3.5 自动化辅助迁移脚本与代码扫描迁移工作量大时靠手工改太容易漏。我写过一个简单的脚本用来扫描代码库中的 Gym API 调用点并给出替换建议。核心思路就是正则匹配和 AST 分析。用 AST 会更可靠因为能正确解析出函数调用的具体位置和参数结构。模板如下import ast import sys class GymAPIVisitor(ast.NodeVisitor): def __init__(self): self.hits [] def visit_Attribute(self, node): if isinstance(node.value, ast.Name) and node.value.id gym: self.hits.append((node.attr, node.lineno)) self.generic_visit(node) def visit_Call(self, node): if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name): if node.func.value.id gym: self.hits.append((fcall:{node.func.attr}, node.lineno)) self.generic_visit(node) with open(sys.argv[1], r) as f: tree ast.parse(f.read()) visitor GymAPIVisitor() visitor.visit(tree) for attr, lineno in visitor.hits: print(f{lineno}: gym.{attr})这个脚本不会自动改代码但能快速找出所有潜在改动点。结合git diff做逐文件核对效率比纯靠眼睛高很多。对于 step 返回值处理的自动化改法可以用正则做粗替换但这类改动必须有测试兜底否则很容易误伤。我个人的建议是自动化工具只用来定位问题实际改写还是要人工判断尤其是done到terminated/truncated的语义拆分机器无法自动理解业务逻辑。4. 常见问题与排查技巧实录4.1 常见报错与解决方案速查表报错信息原因解决方案AttributeError: module gymnasium has no attribute core混用了 Gym 和 Gymnasium 的 API 引用统一import gymnasium as gym避免直接访问gym.coreTypeError: reset() got an unexpected keyword argument seed环境类没有把seed定义为关键字参数改写reset(self, *, seedNone, optionsNone)并调用super().reset(seedseed)ValueError: Buffer dtype mismatchBox空间 dtype 不匹配显式指定dtypenp.float32并检查传入观测的 dtypeRuntimeError: An environmentsreset()method must return (obs, info)环境reset返回值格式不符合新 API返回(obs, info)而不是obsgymnasium.error.InvalidAction: action must be a numpy arrayDiscrete空间的动作类型要求严格把动作转换为np.int64或np.int32NameError: name gym is not defined老代码仍直接import gym但环境中没有安装gym改为import gymnasium as gym4.2 关于truncated标志的语义陷阱这个算是我迁移过程中遇到的最复杂的逻辑问题。很多老代码里根本没有truncated这个概念所有结束都用一个done表示。迁移后如果简单地用terminated or truncated来填充done对某些算法是对的对某些算法是错的。具体来说DQN 系列的算法通常会把done当作“是否不进行下一步 bootstrap”的标志所以truncated和terminated对它们的影响是一样的用or合并没问题。但像基于 TD 的连续控制算法DDPG、TD3、SAC里如果truncated被当作结束标志会导致目标 Q 值被直接当 0训练出来的值函数会系统性偏低。也就是说如果任务本身没有真正的失败状态只是步数超限正确的做法是done terminated # 不能把 truncated 混进去我建议在回放缓冲区里把terminated和truncated分开存储或者在info里单独记录TimeLimit.truncated标志这样后续做任何算法实验时可以灵活切换。很多开源库比如 Stable-Baselines3已经这么做了但自研项目里容易被忽视。4.3 Render 相关的兼容性问题渲染这块也是迁移时的高发问题区。老代码里常见的写法env gym.make(MyEnv-v0) env.render(modehuman)Gymnasium 下要写成env gym.make(MyEnv-v0, render_modehuman) env.render()原因在于render_mode必须在构造环境时确定因为底层渲染器的生命周期是绑定在环境实例上的。如果你在make之后动态切换渲染模式很多时候不会报错但实际的渲染行为可能不符合预期比如human模式可能没有真正把画面推送到窗口。另外Gymnasium 的render_mode可选值更规范包括human、rgb_array、ansi、single_rgb_array等。如果自定义环境里实现了自己的render需要根据render_mode分别返回不同的内容。比如human模式返回 None 或直接往窗口绘制rgb_array模式返回(H, W, 3)的 uint8 数组。这些细节在 Gym 时代没有强制但在 Gymnasium 里是会被env_checker验证的。4.4 环境检查器 env_checker 的使用与误报处理Gymnasium 提供了一个非常好用的工具from gymnasium.utils.env_checker import check_env env MyEnv() check_env(env)它会对环境的观测空间、动作空间、步进逻辑、reset 逻辑、渲染接口做全面检查。这个在迁移过程中可以帮你快速定位问题尤其是那些隐藏的“非标准行为”。但也要注意这个检查器偶尔会出现误报特别是当你故意使用了某些非常规但合理的环境设计时。比如动作空间是spaces.Dict但内部只支持特定组合的字典键检查器会遍历所有可能的组合然后报一个InvalidAction但这可能是你故意设置的约束。这种情况下合理的做法是被迫在make时传入disable_env_checkerTrue或者通过 Wrapper 做一层转换把 Dict 动作映射到真正的合法空间。4.5 记录 Episode 统计信息时的 API 变化另一个常见迁移问题在RecordEpisodeStatistics的返回值上。老 Gym 里这个 Wrapper 会把统计信息写入info[episode]字典中包含r和l两个键。Gymnasium 基本保留了这套用法但键名可能有所不同。如果你依赖info[episode][r]来提取奖励建议迁移后先跑一个简单环境验证一下 key 是否存在避免训练时取不到值导致隐性 bug。有种更稳妥的替代方案是自己实现一个统计 Wrapper不依赖内部键名并在每个 episode 结束时把episode_reward和episode_length显式写进info。这样无论底层库怎么变你的上层代码不会受影响。示例class EpisodeStatsWrapper(gym.Wrapper): def __init__(self, env): super().__init__(env) self.episode_reward 0.0 self.episode_length 0 self.episode_count 0 def reset(self, **kwargs): obs, info self.env.reset(**kwargs) self.episode_reward 0.0 self.episode_length 0 return obs, info def step(self, action): obs, reward, terminated, truncated, info self.env.step(action) self.episode_reward reward self.episode_length 1 if terminated or truncated: self.episode_count 1 info[episode] { r: self.episode_reward, l: self.episode_length, count: self.episode_count, } return obs, reward, terminated, truncated, info4.6 多环境并行与向量化接口的差异如果你的项目里用了gym.vector.AsyncVectorEnv或gym.vector.SyncVectorEnv迁移时也要格外留意。Gymnasium 提供了gymnasium.vector但内部实现和 API 有差异。老写法from gym.vector import AsyncVectorEnv envs AsyncVectorEnv([lambda: gym.make(MyEnv-v0) for _ in range(4)])迁移后from gymnasium.vector import AsyncVectorEnv envs AsyncVectorEnv([lambda: gym.make(MyEnv-v0) for _ in range(4)])看着像是只改了导入路径但如果子环境内部使用了 Gymnasium 规范vector的reset返回也是一个(obs, info)元组obs是一个堆叠后的批量观测。另外AsyncVectorEnv的共享内存类型检查更严格如果观测不是np.ndarray或无法转换启动时会直接报错。所以迁移后多环境并行这块也要单独跑一下。5. 工具选型与迁移策略建议5.1 第三方库的兼容现状迁移过程中你依赖的强化学习库大概率也已经切到了 Gymnasium。比如 Stable-Baselines3 从 2.0 开始就完全基于 Gymnasium老版本会提示你必须用gymnasium作为环境后端。如果你的项目依赖了 RLlib、Sample Factory 或老版baselines它们的 Gymnasium 适配程度各不相同必须提前调研清楚。我当时的项目虽然是自研算法但用了tensorboard做日志、optuna做超参搜索、imitation做行为克隆。其中imitation在新版本里已经支持 Gymnasium但如果你锁的是老版本环境类型检查可能过不去。解决方案是把这些中间库的版本全部升级到与 Gymnasium 兼容的版本同时留意它们的requirements.txt是否锁定老 Gym避免在安装时又把 Gym 装回来。5.2 一步到位还是逐步灰度这个问题没有标准答案取决于你的代码规模和风险承受能力。我的建议是分三步走第一步建立起独立的 Gymnasium 测试环境把自定义环境迁移过去跑通env_checker并复现一次随机策略交互确认底层环境没问题。第二步把算法核心的训练循环迁移过去保持自定义环境不变如果还没迁完用gymnasium.make包装原有环境作为临时兼容观察训练曲线是否与老版本对齐。第三步清理所有兼容代码删除gym引用统一为gymnasium跑全量回归测试。这种灰度迁移的好处是你可以随时定位问题范围训练曲线不对是环境的问题还是算法的问题通过分步切换可以很清楚地回答。5.3 代码改造之外别忘了文档和实验记录技术细节之外还有一件容易忽略的事迁移后实验记录的连续性。如果你有一批基于老 Gym 跑出来的基线实验结果迁移后环境行为可能因为随机种子、空间 dtype、截断语义等变化而产生微小的不一致。虽然这些不一致通常不会改变策略方向但在对比实验结果时建议在实验记录里标注“Gymnasium 迁移后”的版本号避免后续做实验对比时产生歧义。我当时把所有迁移相关的 commit 单独打了一个 tag比如migration-gymnasium-0.29并在 README 里更新了环境依赖说明和已知差异。这套做法在团队协作时尤其重要因为你不想让队友在一个混合了新旧 API 的代码库上做开发。6. 最后的实操心得这一次迁移做下来我最大的一个体会是import gymnasium as gym只是表面功夫真正的迁移难点在于done标志的语义拆分以及环境接口的规范性。如果你原来写的环境本身就严格遵循 Gym 官方规范比如所有动作和观测都有明确的Space声明reset和step签名标准那么迁移到 Gymnasium 基本就是改两个方法签名的事。但如果你以前写过不少“野路子”环境——比如直接返回dict而不是Space声明的观测、或者把done和truncated混着用——那迁移的工程量可能会比预想的大不少。另外也别小看super().reset(seedseed)这一行。很多自研环境在迁移后训练结果无法复现问题就出在这里。还有一点就是不要为了省事而直接跳过env_checker它能在五分钟内帮你把隐藏的接口问题全部揪出来省下后面几天排查的功夫。如果团队里有人对这次迁移有顾虑我通常会给一个简单的定心丸Gymnasium 的前身就是 GymAPI 的兼容性保留了八成以上真正需要动脑子的地方只有 step 返回值里新增的两个布尔值。只要你理解terminated和truncated的语义区别其他几乎都是机械式的替换工作。而且迁移完成后你会发现代码更规范了跑在新 Python 版本上也不会因为 Gym 的停更而提心吊胆。本文还有配套的精品资源点击获取