CleanRL（强化学习算法的简洁实现）

CleanRL 是一个深度强化学习库，提供高质量的单文件实现，并具备适合研究的功能。其实现简洁明了，同时我们也可以通过 AWS Batch 将其扩展到运行数千个实验。CleanRL 的亮点功能包括：

• 📜 单文件实现
  • 算法变体的所有细节都集中在一个独立的文件中。
  • 例如，我们的 ppo_atari.py 只有 340 行代码，却包含了 PPO 如何与 Atari 游戏配合工作的全部实现细节，因此对于那些不想阅读整个模块化库的人来说，这是一个非常好的参考实现。
• 📊 已基准化的实现（在 https://benchmark.cleanrl.dev 上有 7 种以上算法和 34 款以上游戏）
• 📈 TensorBoard 日志记录
• 🪛 通过种子设置实现本地可重复性
• 🎮 游戏过程视频录制
• 🧫 使用 Weights and Biases 进行实验管理
• 💸 与 Docker 和 AWS 的云端集成

您可以在我们的 JMLR 论文 和 文档 中了解更多关于 CleanRL 的信息。

值得关注的 CleanRL 相关项目：

• corl-team/CORL：以 CleanRL 风格实现的离线强化学习算法
• pytorch-labs/LeanRL：使用 CUDAGraphs 对 CleanRL 强化学习算法进行快速优化的 PyTorch 实现。

ℹ️ 对 Gymnasium 的支持：Farama-Foundation/Gymnasium 是 openai/gym 的下一代版本，将继续维护并引入新功能。请参阅他们的 公告 以获取更多详细信息。我们正在迁移到 gymnasium，进度可以在 vwxyzjn/cleanrl#277 中跟踪。

⚠️ 注意：CleanRL 并非模块化库，因此不适合被导入。为了减少代码重复，我们将每个 DRL 算法变体的所有实现细节都设计得易于理解，所以 CleanRL 既有优点也有缺点。如果您希望 1) 理解某个算法变体的所有实现细节，或 2) 原型化其他模块化 DRL 库不支持的高级功能（CleanRL 代码量较少，调试体验极佳，且无需像某些模块化 DRL 库那样进行大量子类化），那么您可以考虑使用 CleanRL。

快速入门

前提条件：

• Python >=3.7.1,<3.11
• uv 0.7.9+

要在本地运行实验，请尝试以下步骤：

git clone https://github.com/vwxyzjn/cleanrl.git && cd cleanrl
uv pip install .

# 或者，您也可以使用 `uv venv`，然后执行
# `python run cleanrl/ppo.py`
uv run python cleanrl/ppo.py \
    --seed 1 \
    --env-id CartPole-v0 \
    --total-timesteps 50000

# 打开另一个终端，进入 `cd cleanrl/cleanrl`
tensorboard --logdir runs

要使用 wandb 进行实验跟踪，请运行以下命令：

wandb login # 仅首次需要
uv run python cleanrl/ppo.py \
    --seed 1 \
    --env-id CartPole-v0 \
    --total-timesteps 50000 \
    --track \
    --wandb-project-name cleanrltest

如果您没有使用 uv，可以使用 requirements.txt 安装 CleanRL：

# 核心依赖
pip install -r requirements/requirements.txt

# 可选依赖
pip install -r requirements/requirements-atari.txt
pip install -r requirements/requirements-mujoco.txt
pip install -r requirements/requirements-mujoco_py.txt
pip install -r requirements/requirements-procgen.txt
pip install -r requirements/requirements-envpool.txt
pip install -r requirements/requirements-pettingzoo.txt
pip install -r requirements/requirements-jax.txt
pip install -r requirements/requirements-docs.txt
pip install -r requirements/requirements-cloud.txt
pip install -r requirements/requirements-memory_gym.txt

要在其他游戏中运行训练脚本：

uv venv

# 经典控制
python cleanrl/dqn.py --env-id CartPole-v1
python cleanrl/ppo.py --env-id CartPole-v1
python cleanrl/c51.py --env-id CartPole-v1

# Atari
uv pip install ".[atari]"
python cleanrl/dqn_atari.py --env-id BreakoutNoFrameskip-v4
python cleanrl/c51_atari.py --env-id BreakoutNoFrameskip-v4
python cleanrl/ppo_atari.py --env-id BreakoutNoFrameskip-v4
python cleanrl/sac_atari.py --env-id BreakoutNoFrameskip-v4

# 新增：使用 envpool 的 Atari 版本可实现 3–4 倍无副作用的速度提升（仅限 Linux）
uv pip install ".[envpool]"
python cleanrl/ppo_atari_envpool.py --env-id BreakoutNoFrameskip-v4
# 大约 5–10 分钟即可学会 Pong-v5
# 可能会出现采样效率降低等副作用
uv run python ppo_atari_envpool.py --clip-coef=0.2 --num-envs=16 --num-minibatches=8 --num-steps=128 --update-epochs=3

# Procgen
uv pip install ".[procgen]"
python cleanrl/ppo_procgen.py --env-id starpilot
python cleanrl/ppg_procgen.py --env-id starpilot

# PPO + LSTM
uv pip install ".[atari]"
python cleanrl/ppo_atari_lstm.py --env-id BreakoutNoFrameskip-v4

您也可以使用 Gitpod 托管的预构建开发环境：

已实现的算法

算法	已实现的变体
✅ 近端策略优化 (PPO)	ppo.py, 文档
	ppo_atari.py, 文档
	ppo_continuous_action.py, 文档
	ppo_atari_lstm.py, 文档
	ppo_atari_envpool.py, 文档
	ppo_atari_envpool_xla_jax.py, 文档
	ppo_atari_envpool_xla_jax_scan.py, 文档)
	ppo_procgen.py, 文档
	ppo_atari_multigpu.py, 文档
	ppo_pettingzoo_ma_atari.py, 文档
	ppo_continuous_action_isaacgym.py, 文档
	ppo_trxl.py, 文档
✅ 深度Q学习 (DQN)	dqn.py, 文档
	dqn_atari.py, 文档
	dqn_jax.py, 文档
	dqn_atari_jax.py, 文档
✅ 分类DQN (C51)	c51.py, 文档
	c51_atari.py, 文档
	c51_jax.py, 文档
	c51_atari_jax.py, 文档
✅ 软演员-评论家 (SAC)	sac_continuous_action.py, 文档
	sac_atari.py, 文档
✅ 深度确定性策略梯度 (DDPG)	ddpg_continuous_action.py, 文档
	ddpg_continuous_action_jax.py, 文档
✅ 双延迟深度确定性策略梯度 (TD3)	td3_continuous_action.py, 文档
	td3_continuous_action_jax.py, 文档
✅ 相位策略梯度 (PPG)	ppg_procgen.py, 文档
✅ 随机网络蒸馏 (RND)	ppo_rnd_envpool.py, 文档
✅ Qdagger	qdagger_dqn_atari_impalacnn.py, 文档
	qdagger_dqn_atari_jax_impalacnn.py, 文档

开放强化学习基准

为了使我们的实验数据更加透明，CleanRL 参与了一个名为 Open RL Benchmark 的相关项目。该项目收录了来自多个流行深度强化学习库的跟踪实验，包括我们自己的 CleanRL、Stable-baselines3、openai/baselines、jaxrl 等。

请访问 https://benchmark.cleanrl.dev/，那里汇集了 Weights and Biases 报告，展示了各种深度强化学习实验的跟踪结果。这些报告是交互式的，研究人员可以轻松查询诸如 GPU 利用率以及智能体游戏过程视频等信息——而这些信息在其他强化学习基准中通常难以获取。未来，Open RL Benchmark 很可能会提供一个数据集 API，方便研究人员轻松访问这些数据（详见 仓库）。

支持与参与

我们有一个 Discord 社区，欢迎前来寻求支持或提问。也欢迎大家在 Github Issues 中提交问题和拉取请求。此外，我们过去的视频记录可以在 YouTube 上观看。

引用 CleanRL

如果您在工作中使用了 CleanRL，请引用我们的技术论文：

@article{huang2022cleanrl,
  author  = {Shengyi Huang and Rousslan Fernand Julien Dossa and Chang Ye and Jeff Braga and Dipam Chakraborty and Kinal Mehta and João G.M. Araújo},
  title   = {CleanRL: 高质量的单文件深度强化学习算法实现},
  journal = {机器学习研究期刊},
  year    = {2022},
  volume  = {23},
  number  = {274},
  pages   = {1--18},
  url     = {http://jmlr.org/papers/v23/21-1342.html}
}

致谢

CleanRL 是一个由社区驱动的项目，我们的贡献者们在多种硬件上运行实验。

• 我们感谢众多贡献者利用自己的计算机进行实验。
• 我们感谢 Google 的 TPU 研究云 提供的 TPU 资源。
• 我们感谢 Hugging Face 的集群提供的 GPU 资源。

CleanRL 快速上手指南

CleanRL 是一个专注于提供高质量、单文件实现的深度强化学习库。其代码简洁清晰，非常适合用于理解算法细节、复现研究或进行快速原型开发。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS, Windows (部分 Atari 环境在 Windows 上可能受限)
• Python 版本: >=3.7.1 且 <3.11
• 包管理工具: 推荐安装 uv (版本 0.7.9+)，它能显著加快依赖安装速度。
  • 安装 uv: curl -LsSf https://astral.sh/uv/install.sh | sh
  • 注：如果不使用 uv，也可使用标准的 pip 和 requirements.txt 进行安装。

安装步骤

方式一：使用 uv 安装（推荐）

这是最快捷的安装方式，自动处理虚拟环境和依赖。

# 克隆仓库
git clone https://github.com/vwxyzjn/cleanrl.git && cd cleanrl

# 安装核心依赖
uv pip install .

如果您需要运行特定环境的游戏（如 Atari, MuJoCo 等），可以按需安装额外依赖：

# 安装 Atari 游戏支持
uv pip install ".[atari]"

# 安装 ProcGen 支持
uv pip install ".[procgen]"

# 安装 EnvPool (Linux 专用，可加速 Atari 训练)
uv pip install ".[envpool]"

方式二：使用 pip 安装

如果不使用 uv，可以通过 requirements.txt 手动安装：

# 安装核心依赖
pip install -r requirements/requirements.txt

# 可选：安装特定环境依赖
pip install -r requirements/requirements-atari.txt
pip install -r requirements/requirements-mujoco.txt
# ... 其他需求文件见 requirements/ 目录

提示：国内用户若遇到下载速度慢的问题，可在上述 pip 或 uv pip 命令后添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华镜像源。

基本使用

CleanRL 的设计理念是单文件即算法。你不需要导入库，而是直接运行对应的 Python 脚本。

1. 运行最简单的实验 (CartPole)

以下命令使用 PPO 算法在 CartPole-v0 环境中训练 50,000 步：

uv run python cleanrl/ppo.py \
    --seed 1 \
    --env-id CartPole-v0 \
    --total-timesteps 50000

2. 查看训练日志

训练过程中产生的日志默认保存在 runs 目录下。启动另一个终端，使用 TensorBoard 查看实时曲线：

cd cleanrl
tensorboard --logdir runs

然后在浏览器访问显示的地址（通常是 http://localhost:6006）。

3. 使用 Weights & Biases (WandB) 追踪实验

若需云端记录实验数据，先登录 WandB，然后添加 --track 参数：

wandb login # 首次使用需输入 API Key

uv run python cleanrl/ppo.py \
    --seed 1 \
    --env-id CartPole-v0 \
    --total-timesteps 50000 \
    --track \
    --wandb-project-name cleanrltest

4. 运行其他游戏示例

• Atari 游戏 (Breakout):

  # 需先执行: uv pip install ".[atari]"
  python cleanrl/dqn_atari.py --env-id BreakoutNoFrameskip-v4
  python cleanrl/ppo_atari.py --env-id BreakoutNoFrameskip-v4
  

• 高速训练 (使用 EnvPool, 仅 Linux):

  # 需先执行: uv pip install ".[envpool]"
  # 可在 5-10 分钟内学会 Pong
  uv run python cleanrl/ppo_atari_envpool.py --env-id PongNoFrameskip-v4 --clip-coef=0.2 --num-envs=16
  

• ProcGen 游戏:

  # 需先执行: uv pip install ".[procgen]"
  python cleanrl/ppo_procgen.py --env-id starpilot
  

注意：CleanRL 不是模块化库，不建议作为 Python 包 import 使用。其优势在于每个算法变体都独立在一个文件中，方便阅读源码和调试具体实现细节。