---

EnvPool 是一个基于 C++ 的批处理环境池，结合了 pybind11 和线程池技术。它具有高性能（在 Atari 游戏上可达约 100 万帧/秒，在 Mujoco 模拟器上使用 DGX-A100 可达约 300 万步/秒）以及兼容的 API 接口（同时支持 gym 和 dm_env，同步与异步模式，单人及多人环境）。目前支持以下环境：

• Atari 游戏
• Mujoco (gym)
• 经典控制强化学习环境：CartPole、MountainCar、Pendulum、Acrobot
• Toy text 强化学习环境：Catch、FrozenLake、Taxi、NChain、CliffWalking、Blackjack
• ViZDoom 单人模式
• DeepMind Control Suite
• Box2D
• Procgen
• Minigrid

以下是 EnvPool 的几大亮点：

• 兼容 OpenAI gym API、DeepMind dm_env API 以及 gymnasium API；
• 管理一个环境池，默认以批处理方式与环境交互；
• 同时支持同步执行和异步执行；
• 支持单人和多人环境；
• 提供易于使用的 C++ 开发者 API，方便添加新环境：自定义 C++ 环境集成；
• 即使仅使用单个环境，也能获得约 2 倍 的速度提升；
• 在 256 核 CPU 上，可实现每秒 100 万帧 的 Atari 游戏模拟或 300 万步 的 Mujoco 步骤模拟，吞吐量是基于 Python 子进程的向量化环境的 20 倍；
• 在低资源环境下（如 12 核 CPU），吞吐量仍是基于 Python 子进程的向量化环境的 3 倍；
• 与现有的 GPU 加速方案（如 Brax 或 Isaac-gym）相比，EnvPool 是一种适用于多种场景的通用解决方案，能够显著加速强化学习中的环境并行化；
• 支持 XLA，可通过 JAX jit 函数实现加速：XLA 接口；
• 与一些现有的强化学习库兼容，例如 Stable-Baselines3、Tianshou、ACME、CleanRL 或 rl_games。
  • Stable-Baselines3 Pendulum-v1 示例；
  • Tianshou CartPole 示例、Pendulum-v1 示例、Atari 示例、Mujoco 示例，以及集成指南；
  • ACME HalfCheetah 示例；
  • CleanRL Pong-v5 示例（用 PPO 和 EnvPool 在 5 分钟内解决 Pong 问题；实验追踪)；
  • rl_games Atari 示例（2 分钟搞定 Pong 和 15 分钟完成 Breakout）以及 Mujoco 示例（5 分钟搞定 Ant 和 HalfCheetah）。

更多详细信息请参阅我们的 arXiv 论文！

安装

PyPI

EnvPool 目前托管在 PyPI 上，支持 Linux、macOS 和 Windows 平台上的 Python 3.11 至 3.14。

您只需运行以下命令即可安装 EnvPool：

$ pip install envpool

安装完成后，打开 Python 控制台并输入：

import envpool
print(envpool.__version__)

如果没有报错，则说明您已成功安装 EnvPool。

平台注意事项：

• PyPI 发布的二进制包无需在运行时单独安装 Qt。
• Windows 版本的 Procgen 包含所需的 Qt 运行时 DLL 文件（Qt5Core.dll 和 Qt5Gui.dll），并与扩展模块一同打包。
• Windows 的源码/发布 CI 使用 Mesa 软件 OpenGL 来验证 MuJoCo 的渲染效果。若要在本地复现该设置，请将 ENVPOOL_DLL_DIR 指向 Mesa DLL 目录，并设置 GALLIUM_DRIVER=llvmpipe 以及 MESA_GL_VERSION_OVERRIDE=4.5COMPAT。
• 从源码构建仍需依赖平台特定的编译工具链，包括 Qt 5。完整的平台配置说明请参阅 从源码构建。

从源代码

请参阅指南。

文档

教程和 API 文档托管在 envpool.readthedocs.io 上。

示例脚本位于 examples/ 文件夹中；基准测试脚本位于 benchmark/ 文件夹中。

基准测试结果

以下历史基准测试表格是在不同的硬件配置下生成的，使用的环境包括 ALE Atari 环境 PongNoFrameskip-v4（带有来自 OpenAI Baselines 的环境包装器）和 Mujoco 环境 Ant-v3。硬件配置包括一台拥有 96 个 CPU 核心、2 个 NUMA 节点的 TPUv3-8 虚拟机，以及一台拥有 256 个 CPU 核心、8 个 NUMA 节点的 NVIDIA DGX-A100。当前位于 benchmark/ 中的脚本使用的是 Gymnasium 的 ALE/Pong-v5 和 Ant-v5。基准对比包括：1) 原生 Python for 循环；2) 最流行的基于 Python 子进程的强化学习环境并行化执行方式，例如 gym.vector_env；3) 据我们所知，在 EnvPool 出现之前最快的强化学习环境执行器 Sample Factory。

我们报告了 EnvPool 在同步模式、异步模式以及 NUMA + 异步模式下的性能，并将其与不同数量的工作进程（即 CPU 核心数）下的基准进行了比较。从结果可以看出，EnvPool 在所有设置下都显著优于基准。在高端配置下，EnvPool 在 256 个 CPU 核心上实现了 Atari 环境每秒 100 万帧、Mujoco 环境每秒 300 万帧的吞吐量，分别是 gym.vector_env 基准的 14.9 倍和 19.6 倍。而在典型的 12 核 CPU 的 PC 配置下，EnvPool 的吞吐量则是 gym.vector_env 的 3.1 倍和 2.9 倍。

Atari 最高 FPS	笔记本电脑 (12)	工作站 (32)	TPU-VM (96)	DGX-A100 (256)
For-loop	4,893	7,914	3,993	4,640
Subprocess	15,863	47,699	46,910	71,943
Sample-Factory	28,216	138,847	222,327	707,494
EnvPool (sync)	37,396	133,824	170,380	427,851
EnvPool (async)	49,439	200,428	359,559	891,286
EnvPool (numa+async)	/	/	373,169	1,069,922

Mujoco 最高 FPS	笔记本电脑 (12)	工作站 (32)	TPU-VM (96)	DGX-A100 (256)
For-loop	12,861	20,298	10,474	11,569
Subprocess	36,586	105,432	87,403	163,656
Sample-Factory	62,510	309,264	461,515	1,573,262
EnvPool (sync)	66,622	380,950	296,681	949,787
EnvPool (async)	105,126	582,446	887,540	2,363,864
EnvPool (numa+async)	/	/	896,830	3,134,287

更多详细信息请参阅 基准测试 页面。

API 使用

以下内容展示了 EnvPool 的同步和异步 API 使用方法。您也可以运行完整的脚本，地址为 examples/env_step.py。

同步 API

import envpool
import numpy as np

# 创建 gym 环境
env = envpool.make("Pong-v5", env_type="gym", num_envs=100)
# 或者使用 envpool.make_gym(...)
obs = env.reset()  # 应该是 (100, 4, 84, 84)
act = np.zeros(100, dtype=int)
obs, rew, term, trunc, info = env.step(act)

在同步模式下，envpool 与 openai-gym/dm-env 非常相似。它具有与原版相同的 reset 和 step 函数。不过，envpool 有一个例外：默认采用批量交互。因此，在创建 envpool 时，需要指定一个 num_envs 参数，用于表示您希望同时运行多少个环境。

env = envpool.make("Pong-v5", env_type="gym", num_envs=100)

传递给 step 函数的 action 的第一个维度应等于 num_envs。

act = np.zeros(100, dtype=int)

您无需在某个环境完成时手动重置它；相反，envpool 中的所有环境都默认启用了自动重置功能。

异步 API

import envpool
import numpy as np

# 创建异步环境
num_envs = 64
batch_size = 16
env = envpool.make("Pong-v5", env_type="gym", num_envs=num_envs, batch_size=batch_size)
action_num = env.action_space.n
env.async_reset()  # 向所有环境发送初始重置信号
while True:
    obs, rew, term, trunc, info = env.recv()
    env_id = info["env_id"]
    action = np.random.randint(action_num, size=batch_size)
    env.send(action, env_id)

在异步模式下，step 函数被拆分为两个部分：send 和 recv 函数。send 接受两个参数：一批动作以及每个动作对应的 env_id，用于指示将动作发送到哪个环境。与 step 不同，send 不会等待环境执行并返回下一个状态，而是在动作被送入环境后立即返回。（这也是其被称为异步模式的原因）。

env.send(action, env_id)

要获取“下一个状态”，我们需要调用 recv 函数。然而，recv 并不能保证您会收到刚刚调用 send 的那些环境的“下一个状态”。相反，最先完成执行的环境会优先被 recv 到。

state = env.recv()

除了 num_envs 之外，还有一个 batch_size 参数。虽然 num_envs 定义了 envpool 总共管理多少个环境，但 batch_size 则指定了每次与 envpool 交互时涉及的环境数量。例如，如果 envpool 中有 64 个环境正在运行，那么每次 send 和 recv 只会与其中 16 个环境进行交互。

envpool.make("Pong-v5", env_type="gym", num_envs=64, batch_size=16)

envpool.make 还有其他可配置的参数，请参阅 EnvPool Python 接口介绍。

渲染

EnvPool 通过 Python 封装暴露了渲染功能。创建环境时设置 render_mode="rgb_array" 可以获取批量的 RGB 输出，或者设置 render_mode="human" 通过 OpenCV 显示单个环境。

import envpool

env = envpool.make(
    "Ant-v5",
    env_type="gymnasium",
    num_envs=4,
    render_mode="rgb_array",
    render_width=480,
    render_height=480,
)
env.reset()
frames = env.render(env_ids=[0, 2])
assert frames.shape == (2, 480, 480, 3)

render() 是以批次为先的，因此即使只渲染一个环境，也会保留批次维度：env.render().shape == (1, H, W, 3)。如果省略 env_ids，EnvPool 会渲染 render_env_id（默认为 0）。camera_id 可以在每次调用时覆盖，而输出尺寸则在创建环境时通过 render_width 和 render_height 固定。

仓库的测试套件也对渲染功能进行了测试。make bazel-test 会对每个支持渲染的环境系列重复进行渲染检查，而 make release-test 则包含一个轮子烟雾测试，在 reset() 后调用 render()。在 Windows 上，MuJoCo 的渲染测试使用了上述相同的 ENVPOOL_DLL_DIR Mesa 预加载钩子，以便使用软件 OpenGL 而不是系统驱动程序。

viewer = envpool.make(
    "WalkerWalk-v1",
    env_type="gymnasium",
    num_envs=1,
    render_mode="human",
    render_env_id=0,
)
viewer.reset()
viewer.render()

render_mode="human" 返回 None，并且目前每次调用仅支持一个环境 ID。此外，它还需要安装 opencv-python。

像素观测

对于 MuJoCo 任务，像素观测也可以通过常规的观测 API 直接暴露出来，只需传递 from_pixels=True 即可。这一路径是在 C++ 中原生实现的，无需通过 Python 端的 render() 进行路由。

pixels = envpool.make(
    "WalkerWalk-v1",
    env_type="gymnasium",
    num_envs=2,
    from_pixels=True,
    frame_stack=3,
    render_width=84,
    render_height=84,
)
obs, info = pixels.reset()
assert obs.shape == (2, 9, 84, 84)

像素观测采用通道优先的布局。当 frame_stack=1 时，每个环境返回 (3, H, W)；当 frame_stack=3 时，EnvPool 会将帧堆叠到通道维度上，返回 (9, H, W)。这直接符合常用的 PyTorch BCHW 规范。如果省略 render_width 或 render_height，EnvPool 会将其默认设置为 84。

贡献

EnvPool 仍处于开发阶段。未来还将添加更多环境，并且我们始终欢迎贡献，以帮助 EnvPool 不断完善。如果您希望参与贡献，请查看我们的贡献指南。

许可证

EnvPool 采用 Apache2 许可证。

其他第三方源代码和数据则遵循各自的许可证。

我们并未将这些第三方的源代码和数据包含在本仓库中。

引用 EnvPool

如果您觉得 EnvPool 对您有帮助，请在您的出版物中引用它。

@inproceedings{weng2022envpool,
 author = {Weng, Jiayi and Lin, Min and Huang, Shengyi and Liu, Bo and Makoviichuk, Denys and Makoviychuk, Viktor and Liu, Zichen and Song, Yufan and Luo, Ting and Jiang, Yukun and Xu, Zhongwen and Yan, Shuicheng},
 booktitle = {Advances in Neural Information Processing Systems},
 editor = {S. Koyejo and S. Mohamed and A. Agarwal and D. Belgrave and K. Cho and A. Oh},
 pages = {22409--22421},
 publisher = {Curran Associates, Inc.},
 title = {Env{P}ool: A Highly Parallel Reinforcement Learning Environment Execution Engine},
 url = {https://proceedings.neurips.cc/paper_files/paper/2022/file/8caaf08e49ddbad6694fae067442ee21-Paper-Datasets_and_Benchmarks.pdf},
 volume = {35},
 year = {2022}
}

免责声明

本项目并非 Sea Limited 或 Garena Online Private Limited 的官方产品。

EnvPool 快速上手指南

EnvPool 是一个基于 C++ 的高性能批量环境池，支持多线程并行执行。它兼容 OpenAI gym、DeepMind dm_env 及 gymnasium API，能够显著提升强化学习训练速度（在 Atari 游戏上可达 ~1M FPS，Mujoco 上可达 ~3M FPS）。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.11 - 3.14
• 前置依赖：
  • 通过 PyPI 安装时通常无需额外配置（Windows 版 Procgen 已内置所需 Qt 运行库）。
  • 若需从源码编译或进行高级定制，可能需要安装 Qt 5 及相关构建工具（详见官方文档 Build From Source 章节）。

安装步骤

推荐使用 pip 直接安装预编译包：

pip install envpool

提示：国内用户若下载缓慢，可使用清华或阿里镜像源加速：

pip install envpool -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，可通过以下命令验证是否成功：

import envpool
print(envpool.__version__)

若无报错并输出版本号，即表示安装成功。

基本使用

EnvPool 默认采用批量交互模式，即一次性并行运行多个环境实例。

同步模式示例

以下示例展示了如何创建 100 个并行的 Pong 游戏环境并进行一步交互：

import envpool
import numpy as np

# 创建环境池：指定环境名称、类型及并行数量
env = envpool.make("Pong-v5", env_type="gym", num_envs=100)

# 重置所有环境，返回观测值形状为 (100, 4, 84, 84)
obs = env.reset()

# 构造动作数组，第一维必须等于 num_envs
act = np.zeros(100, dtype=int)

# 执行一步交互
# 返回值包含：观测值、奖励、终止标志、截断标志、信息字典
obs, rew, term, trunc, info = env.step(act)

关键特性说明：

1. 批量操作：step 和 reset 函数自动处理所有并行环境，输入的动作数组第一维需与 num_envs 一致。
2. 自动重置：当某个子环境结束时（done=True），EnvPool 会自动将其重置，无需手动干预。
3. API 兼容：接口设计与标准 gym 高度一致，易于集成到 Stable-Baselines3、Tianshou 等现有 RL 库中。