Gymnasium 深度研究报告
一句话定位
Gymnasium 是强化学习（RL）领域的事实标准 API——它是 OpenAI Gym 的官方维护分支，由非营利组织 Farama Foundation 维护，为单智能体 RL 环境提供统一的 Python 接口。截至 2026 年 5 月，Gymnasium 自身累计下载量超过 7000 万次，加上其前身 Gym 的 3.3 亿次下载，整个生态的安装量已超过 4 亿次 Farama Foundation 安装统计。
1. 起源与历史：从 OpenAI Gym 到 Gymnasium
1.1 OpenAI Gym 的诞生与停滞
2016 年，OpenAI 发布了 Gym 库，目的是为 RL 研究提供一个标准化的环境接口。在 Deep Q-Network（DQN）于 2013 年展示出通用神经网络算法可以在 Atari 游戏上达到专家级表现之后 [Mnih et al., 2013]，RL 领域迎来了爆发式增长，但各研究团队各自实现环境接口，导致结果难以复现和比较。Gym 解决了这个问题。
然而，OpenAI 在 2021 年前后逐渐停止了对 Gym 的维护。Gym 的最后一个官方版本停留在 v0.21（旧 API）和 v0.26（引入了部分 breaking changes 但未完成过渡）。
1.2 Farama Foundation 接手
2021 年，原 Gym 的维护团队将项目移交给了新成立的 Farama Foundation——一个专门维护开源 RL 基础设施的非营利组织。项目被重命名为 Gymnasium，并于 2022 年 10 月正式作为独立项目发布。
关键时间线：
| 时间 | 事件 |
|---|---|
| 2016 | OpenAI 发布 Gym |
| 2021 | OpenAI 停止维护，Farama Foundation 接手 |
| 2022.10 | Gymnasium 作为独立项目正式发布 |
| 2024.07 | Gymnasium 白皮书发布（arXiv:2407.17032） |
| 2024.10 | Gymnasium v1.0.0 发布——首个稳定 API |
| 2025.11 | 白皮书被 NeurIPS 2025 Datasets & Benchmarks 接收 |
| 2026.04 | 最新版本 v1.3.0 发布 |
Gymnasium 白皮书明确写道："Gymnasium is a maintained fork of OpenAI's Gym library by its maintainers (OpenAI handed over maintenance a few years ago to an outside team), and is where future maintenance will occur going forward." GitHub
2. Farama Foundation：背后的非营利组织
Farama Foundation 的使命是以中立、非营利的方式维护全球开源 RL 工具。它目前维护着超过 15 个项目，构成了 RL 研究的基础设施层。
2.1 核心项目矩阵
| 项目 | 定位 | 累计下载量 |
|---|---|---|
| Gymnasium | 单智能体 RL 环境标准 API | 7000 万+ |
| PettingZoo | 多智能体 RL（MARL）环境 API | 520 万+ |
| Arcade Learning Environment (ALE) | Atari 2600 模拟器 | 919 万+ |
| Minigrid | 网格世界环境 | 107 万+ |
| Gymnasium-Robotics | 机器人仿真环境 | 54 万+ |
| Shimmy | 跨 API 兼容层 | 478 万+ |
| MO-Gymnasium | 多目标 RL | 26 万+ |
| HighwayEnv | 自动驾驶仿真 | 23 万+ |
| ViZDoom | Doom 游戏环境 | 35 万+ |
2.2 治理模式
Farama 采用志愿者维护 + 社区捐赠的模式。核心维护者包括 Mark Towers（University of Southampton）、Jordan Terry、Ariel Kwiatkowski（Meta AI / FAIR）等人。项目通过 GitHub Sponsors 接受捐赠。
3. 核心 API 设计
Gymnasium 的核心哲学是：环境是一个简单的 Python 类，通过 reset() 和 step() 两个方法与智能体交互。
3.1 最小运行示例
import gymnasium as gym
env = gym.make("CartPole-v1", render_mode="human")
observation, info = env.reset(seed=42)
for _ in range(1000):
action = env.action_space.sample() # 随机策略
observation, reward, terminated, truncated, info = env.step(action)
if terminated or truncated:
observation, info = env.reset()
env.close()
3.2 step() 的五元组返回值
这是 Gymnasium 与旧 Gym 最核心的区别：
| 返回值 | 类型 | 含义 |
|---|---|---|
observation |
ObsType |
环境的新观测 |
reward |
float |
即时奖励 |
terminated |
bool |
任务自然结束（成功/失败） |
truncated |
bool |
因外部约束结束（超时/步数限制） |
info |
dict |
辅助诊断信息 |
terminated vs truncated 的区分是 Gymnasium 最重要的设计决策之一。在旧 Gym 中，只有一个 done 标志，无法区分"智能体真的完成了任务"和"只是因为时间到了"。这对 value-based 方法中的 bootstrap 操作至关重要：
# 正确的 bootstrap 逻辑
if terminated:
next_value = 0 # 自然结束，没有未来价值
elif truncated:
next_value = value_fn(next_obs) # 超时截断，需要估计剩余价值
3.3 空间系统（Spaces）
Gymnasium 提供了丰富的空间类型来描述观测和动作：
| 空间类型 | 描述 | 示例 |
|---|---|---|
Box |
连续张量空间 | Box(low=-1, high=1, shape=(4,)) |
Discrete |
离散整数空间 | Discrete(2) — 左/右 |
MultiDiscrete |
多维离散空间 | MultiDiscrete([3, 2]) |
MultiBinary |
多维二值空间 | MultiBinary(5) |
Text |
字符串空间 | Text(max_length=10) |
Dict |
字典复合空间 | Dict({"pos": Box(...), "vel": Box(...)}) |
Tuple |
元组复合空间 | Tuple((Discrete(2), Box(...))) |
Graph |
图结构空间 | 节点+边+全局属性 |
Sequence |
变长序列空间 | Sequence(Box(...)) |
v1.1 还新增了 概率掩码采样（space.sample(probability=...)），允许策略直接输出概率分布进行采样 Gymnasium v1.1 Release Notes。
4. 内置环境家族
Gymnasium 内置了五大类环境，覆盖从入门教学到前沿研究的各种复杂度：
4.1 Classic Control（经典控制）
5 个环境：Acrobot、CartPole、Mountain Car、Continuous Mountain Car、Pendulum。基于真实物理问题，状态和动作空间较小，适合作为 RL 算法的入门测试。所有环境在初始状态上具有随机性 Classic Control 文档。
4.2 Box2D
基于 2D 物理引擎的玩具游戏：Lunar Lander、Car Racing、Bipedal Walker。使用 PyGame 渲染，是社区中最受欢迎的基准测试之一。v1.2.3 将 Box2D 依赖从 box2d-py 迁移到了 box2d v1.2.3 Release Notes。
4.3 Toy Text
极简离散环境：Blackjack、Taxi、Cliff Walking、Frozen Lake。状态和动作空间极小，适合调试 RL 算法实现。v1.3.0 新增了 Taxi-v4，修复了 is_rainy 的实现 bug v1.3.0 Release Notes。
4.4 MuJoCo
基于 MuJoCo 物理引擎的连续控制任务：HalfCheetah、Hopper、Humanoid、Ant、Swimmer、Walker2d、Pusher、Reacher 等。这是深度 RL 研究中最常用的连续控制基准。v1.0 引入了 MuJoCo v5 环境，支持最新的 MuJoCo 版本。v1.1 新增了 RGBD 渲染（同时输出 RGB 和深度图）MuJoCo 文档。
4.5 Atari（已独立为 ALE）
Atari 2600 游戏环境（Pong、Breakout、Space Invaders 等 60+ 款游戏）在 v1.0 中从 Gymnasium 核心剥离，迁移到了独立的 Arcade Learning Environment (ALE) 项目。这是为了完成一个长达数年的上游化进程——将 DeepMind 和 OpenAI 各自维护的 ALE 分支统一。现在用户需要 import ale_py 来注册 Atari 环境 Gymnasium v1.0 博客。
5. 关键特性深度解析
5.1 Wrapper 系统
Wrapper 是 Gymnasium 最强大的扩展机制。通过嵌套包装，可以在不修改原始环境代码的情况下变换观测、奖励、动作等：
gymnasium.wrappers
├── ObservationWrapper # 变换观测
├── RewardWrapper # 变换奖励
├── ActionWrapper # 变换动作
├── RecordVideo # 录制视频
├── RecordEpisodeStatistics # 记录回合统计
├── NormalizeObservation # 观测归一化
├── NormalizeReward # 奖励归一化
├── TimeLimit # 时间限制
├── FrameStackObservation # 帧堆叠
├── FlattenObservation # 展平观测
├── ResizeObservation # 缩放图像观测
├── ClipReward # 裁剪奖励
├── TransformObservation # 自定义观测变换
├── TransformReward # 自定义奖励变换
├── TransformAction # 自定义动作变换
├── StickyAction # 动作粘滞（模拟随机延迟）
├── AddWhiteNoise # 添加白噪声（v1.2.0）
├── ObstructView # 遮挡视野（v1.2.0）
├── DiscretizeObservation # 离散化观测（v1.2.1）
├── DiscretizeAction # 离散化动作（v1.2.1）
├── RepeatAction # 重复动作（v1.3.0）
└── DelayObservation # 延迟观测（v1.0）
v1.0 的重大变化：Env 和 VectorEnv 的 Wrapper 被分离到不同命名空间（gymnasium.wrappers vs gymnasium.wrappers.vector），因为两者不再共享继承关系。
5.2 Vector Environments（向量化环境）
v1.0 对向量化环境进行了彻底重构：
Env和VectorEnv现在是两个独立的基类（旧版本中VectorEnv继承自Env，这在语义上不正确）- 新增
gymnasium.make_vec()函数，一行代码创建多个并行环境 - 支持三种向量化模式：
sync（同步）、async（异步）、vector_entry_point（环境自定义） - v1.1 新增了三种 autoreset 模式：
next-step、same-step、disabled，兼容旧版行为
# 一行创建 3 个并行环境
envs = gym.make_vec("CartPole-v1", num_envs=3, vectorization_mode="async")
5.3 Functional Environments（函数式环境）
v1.0 引入了 FuncEnv——函数式环境范式。它将环境的动态分解为纯函数：
transition(state, action)→ 状态转移observation(state)→ 观测reward(state, action, next_state)→ 奖励terminal(state)→ 终止判断
这种设计使得环境可以轻松地在 JAX 中实现，利用 jit 编译和 vmap 向量化获得巨大的性能提升。这对于 planning 算法（如 MCTS、模型预测控制）特别有用。
5.4 跨框架互操作
v1.0 和 v1.1 大幅改进了跨深度学习框架的支持：
JaxToTorch、JaxToNumpy、NumpyToTorch等转换 Wrapper- 完整的 DLPack API 支持（零拷贝张量转换）
- v1.2.0 新增
ArrayConversion通用转换 Wrapper，支持所有 Array API 兼容框架
6. 版本演进与最新动态
6.1 v1.0.0（2024-10-08）—— 里程碑
超过 200 个 PR 合并，核心变化：
Env/VectorEnv分离make_vec()函数FuncEnv函数式环境- MuJoCo v5 环境
- 移除插件系统（需显式
import外部库） - ALE 独立为单独项目
- 承诺：这是可预见未来最后一次 breaking change
6.2 v1.1.0（2025-02-26）
- 概率掩码采样
- RGBD 渲染
- Autoreset 模式支持
- DLPack 完整支持
6.3 v1.2.0（2025-06-27）
- MuJoCo v2/v3 迁移至 Gymnasium-Robotics
- Python 3.13 支持（放弃 3.8/3.9）
AddWhiteNoise、ObstructViewWrapperArrayConversion通用转换
6.4 v1.3.0（2026-04-22）—— 当前最新
Taxi-v4环境RepeatActionWrapper- pygame → pygame-ce 迁移（解锁 Python 3.14 兼容性）
- 向量环境内存泄漏修复
- 新增 10 个第三方环境（含网络安全类别）
7. 生态系统全景
7.1 训练库兼容性
几乎所有主流 RL 训练库都支持 Gymnasium API：
| 训练库 | 类型 | 说明 |
|---|---|---|
| CleanRL | 单文件实现 | 官方推荐新手使用 |
| Stable-Baselines3 | 经典算法集 | PPO、A2C、SAC、TD3 等 |
| RLlib | 分布式 | Ray 生态 |
| Tianshou | PyTorch | 清华大学维护 |
| SB3-Contrib | SB3 扩展 | TRPO、QR-DQN 等 |
| AgileRL | 进化 RL | 结合进化算法 |
7.2 第三方环境生态
Gymnasium 的第三方环境列表持续增长，覆盖领域包括：
- 机器人：Gymnasium-Robotics、panda-gym、Metaworld、Robo-gym
- 自动驾驶：HighwayEnv、BlueSky-Gym（空中交通）
- 游戏：ViZDoom（Doom）、Craftium（Minecraft-like）、Procgen2
- 金融交易：AnyTrading
- 网络安全（v1.3.0 新增类别）
- 多目标 RL：MO-Gymnasium
- 安全 RL：Safety-Gymnasium、Robust-Gymnasium（ICLR 2025）
7.3 多智能体扩展：PettingZoo
PettingZoo 是 Gymnasium 的多智能体版本，支持两种 API 风格：
- AEC API（Agent Environment Cycle）：顺序决策
- Parallel API：同步并行决策
PettingZoo 累计下载量超过 520 万次，支持 Python 3.10-3.14。
8. 从 OpenAI Gym 迁移
如果你还在使用旧版 OpenAI Gym（import gym），以下是迁移的核心变化：
| 组件 | 旧 Gym v0.21 | 新 Gymnasium |
|---|---|---|
| 导入 | import gym |
import gymnasium as gym |
| 重置 | obs = env.reset() |
obs, info = env.reset() |
| 种子 | env.seed(42) |
env.reset(seed=42) |
| 步进 | obs, reward, done, info = env.step(a) |
obs, reward, terminated, truncated, info = env.step(a) |
| 渲染 | env.render(mode="human") |
gym.make(id, render_mode="human") |
| Bootstrap | (1-done) * gamma * next_val |
(1-terminated) * gamma * next_val |
对于无法升级的旧环境，可以使用 Shimmy 兼容层包装。
9. 学术影响与引用
Gymnasium 白皮书 "Gymnasium: A Standard Interface for Reinforcement Learning Environments" 已被 NeurIPS 2025 Datasets & Benchmarks 接收 NeurIPS 2025 Poster。引用格式：
@article{towers2024gymnasium,
title={Gymnasium: A Standard Interface for Reinforcement Learning Environments},
author={Towers, Mark and Kwiatkowski, Ariel and Terry, Jordan and Balis, John U and
De Cola, Gianluca and Deleu, Tristan and Goul{\~a}o, Manuel and
Kallinteris, Andreas and Krimmel, Markus and KG, Arjun and others},
journal={arXiv preprint arXiv:2407.17032},
year={2024}
}
白皮书指出，截至 2025 年 4 月，Gymnasium 月下载量已超过 100 万次，累计超过 1800 万次安装（该数字在 2026 年 5 月已增长至 7000 万+）。
10. 总结与展望
核心价值
Gymnasium 解决了 RL 研究中三个根本问题：
- 标准化：统一的
reset/step接口使得算法和环境可以任意组合 - 可复现性：严格的版本控制（
-v0、-v1后缀）和种子机制 - 生态效应：作为"API 标准"，它连接了环境开发者和算法开发者两个社区
未来方向
根据 v1.0 发布博客，Gymnasium 的核心 API 已进入长期稳定阶段。未来的发展重点可能是：
- 函数式环境（JAX 原生）的进一步推广
- 更多垂直领域的第三方环境
- Python 版本跟进（已支持到 3.14）
- 与 LLM-based agent 的接口适配（站内已有论文如 "Healthcare AI GYM for Medical Agents" 使用 gymnasium-compatible 环境训练医疗 AI arXiv:2605.02943）
补充说明
- 依据范围：本报告基于 Gymnasium 官方文档、GitHub 仓库、Farama Foundation 官网、arXiv 白皮书及发布说明，所有关键论断均可通过内联链接一键核实。
- 尚需核实的点：Gymnasium 的具体财务数据（捐赠金额）、各训练库对 v1.3.0 的兼容性更新进度未逐一验证，建议查阅各训练库的 release notes。