CleanRL 快速上手指南：5 分钟跑通你的第一个 PPO 强化学习实验

CleanRL 快速上手指南：5 分钟跑通你的第一个 PPO 强化学习实验

【免费下载链接】cleanrlHigh-quality single file implementation of Deep Reinforcement Learning algorithms with research-friendly features (PPO, DQN, C51, DDPG, TD3, SAC, PPG)项目地址: https://gitcode.com/GitHub_Trending/cl/cleanrl

CleanRL 是每种算法都塞进一个 Python 文件的强化学习库：PPO、DQN、DDPG、TD3、SAC、C51 等经典算法各一个独立脚本，都只有三行代码加一个 main 函数那么薄。适合想快速训出智能体的新手，也适合想彻底搞懂算法内部细节的人。

为什么选 CleanRL：把算法源码变成一遍读完的参考实现

用模块化深度学习框架训练强化学习（让智能体在试错中学会决策）时，你往往想确认算法里某个细节怎么处理的，结果要在多个模块间来回跳；想改一行逻辑，又得先做一层子类。CleanRL 的答案很直接：一个算法变体的完整流程——网络搭建、轨迹收集、优势估计、参数更新——全部装进一个独立脚本。比如跑 Atari 游戏的 PPO 脚本只有 340 行，一次读完就是一份参考实现，不用翻任何框架源码。代价是放弃模块化、接受部分代码重复，换来的是"从头读到尾"的体验。如果你的目标是快速验证想法或者搞懂算法细节，这笔交换很划算。

三步装好 CleanRL 并跑通最小版本 🔧

项目用 uv（更快的 Python 依赖管理工具）管理依赖，官方要求 Python 3.7.1–3.10，注意 3.11 及以上不支持。三条命令完成全部工作：

git clone https://gitcode.com/GitHub_Trending/cl/cleanrl && cd cleanrl uv pip install . uv run python cleanrl/ppo.py --seed 1 --env-id CartPole-v0 --total-timesteps 50000

第一行克隆仓库并进入项目根目录；第二行按 pyproject.toml 锁定版本安装核心依赖；第三行用 PPO（近端策略优化，一种主流的强化学习训练算法）在 CartPole（经典的"小车保持杆平衡"控制问题）上训练 5 万步，普通机器几分钟跑完。训练日志实时写入本地runs目录，另开终端执行tensorboard --logdir runs就能看到下面的训练曲线界面。

项目内部地图：按"算法即文件"快速定位

目录组织遵循一条规则——算法变体即文件，PPO 跑 Atari 就是ppo_atari.py，DQN 跑 Atari 就是dqn_atari.py，抓住它就不会迷路：

cleanrl/ # 核心：每个算法变体一个单文件训练脚本 cleanrl_utils/ # 画曲线、复现实验等辅助工具 tests/ # 单元测试，快速验证环境是否装对 benchmark/ # 各算法基准实验的一键复现脚本 docs/ # 官方文档与各算法基准数据、训练曲线 requirements/ # atari/mujoco/jax 等分平台依赖清单

日常最常打开的是 cleanrl/ 下的脚本，想改参数就直接打开对应文件；跑实验前，去 docs/ 对应算法目录瞄一眼基准数据，能帮你判断自己的训练结果是否正常；画图、复现等辅助功能在 cleanrl_utils/。

高频参数速查：想做什么就拧哪个旋钮

CleanRL 没有全局配置文件：每个脚本内部用一个Args类存放全部默认值，命令行没传的参数就取默认。日常用到的高频参数就下面五个。

• 只想先看看效果→--total-timesteps。它决定智能体与环境交互的总次数，直接控制训练时长；从 50000 调到 5000，几秒钟就能验证环境是否跑通。
• 想换游戏→--env-id。环境 ID 决定智能体在哪训练，比如换成Acrobot-v1；注意连续动作类环境要同时换到ppo_continuous_action.py这类对应脚本。
• 想复现结果→--seed。固定随机种子后，同样的配置两次训练结果一致，做消融对比时只改这一个参数。
• 想加快训练→--num-envs。并行环境数，默认 4；调大后一轮收集更多轨迹，训练时间近乎同比例缩短。
• 想把实验记录到云端→--track。开启 WandB 实验追踪，配合--exp-name给实验命名；前提是已完成登录，见下一节。

常见报错怎么解决：4 个新手必踩的坑 📌

现象：用 Python 3.11+ 安装依赖失败或启动即报错。原因：官方支持范围是 3.7.1–3.10（不含 3.11），部分锁定版本的依赖没有提供更新版本对应的安装包。解法：给项目单独建一个 3.10 的虚拟环境，uv venv --python 3.10即可自动完成。

现象：随手uv pip install torch装了最新版 PyTorch，随后脚本报错。原因：核心依赖版本被项目锁定，最新版框架与这套单文件代码不兼容。解法：始终走官方入口安装；坚持用 pip 的话，执行pip install -r requirements/requirements.txt，不要在环境里自行补装框架包。

现象：加上--track后脚本卡住不动。原因：WandB 追踪需要身份认证，未登录时进程会停在认证环节。解法：先单独执行wandb login完成登录，再重新跑训练命令。

现象：运行ppo_atari.py立刻报某个模块找不到。原因：Atari、MuJoCo、Procgen 等可选环境不在核心依赖里，对应库根本没装。解法：先装对应扩展，例如uv pip install ".[atari]"，再启动脚本。

下一步

跑通之后建议做两件事：一是在 docs/rl-algorithms/ 里翻一遍各算法的基准数据与训练曲线，建立"正常结果长什么样"的参照；二是看看 benchmark/，那里提供各算法完整基准实验的一键复现脚本。现在就可以动手：把刚才的命令里--env-id换成Acrobot-v1再跑一次，对比两条曲线的收敛速度差异。

【免费下载链接】cleanrlHigh-quality single file implementation of Deep Reinforcement Learning algorithms with research-friendly features (PPO, DQN, C51, DDPG, TD3, SAC, PPG)项目地址: https://gitcode.com/GitHub_Trending/cl/cleanrl