CleanRL is a Deep Reinforcement Learning library that provides high-quality single-file implementation with research-friendly features. The implementation is clean and simple, yet we can scale it to run thousands of experiments using AWS Batch. The highlight features of CleanRL are:
- ๐ Single-file implementation
- Every detail about an algorithm is put into the algorithm's own file. It is therefore easier to fully understand an algorithm and do research with.
- ๐ Benchmarked Implementation (7+ algorithms and 34+ games at https://benchmark.cleanrl.dev)
- ๐ Tensorboard Logging
- ๐ช Local Reproducibility via Seeding
- ๐ฎ Videos of Gameplay Capturing
- ๐งซ Experiment Management with Weights and Biases
- ๐ธ Cloud Integration with docker and AWS
You can read more about CleanRL in our technical paper and documentation.
Good luck have fun ๐
Prerequisites:
- Python 3.8+
- Poetry
To run experiments locally, give the following a try:
git clone https://github.com/vwxyzjn/cleanrl.git && cd cleanrl
poetry install
# alternatively, you could use `poetry shell` and do
# `python run cleanrl/ppo.py`
poetry run python cleanrl/ppo.py \
--seed 1 \
--gym-id CartPole-v0 \
--total-timesteps 50000
# open another temrminal and enter `cd cleanrl/cleanrl`
tensorboard --logdir runs
To use experiment tracking with wandb, run
wandb login # only required for the first time
poetry run python cleanrl/ppo.py \
--seed 1 \
--gym-id CartPole-v0 \
--total-timesteps 50000 \
--track \
--wandb-project-name cleanrltest
To run training scripts in other games:
poetry shell
# classic control
python cleanrl/dqn.py --gym-id CartPole-v1
python cleanrl/ppo.py --gym-id CartPole-v1
python cleanrl/c51.py --gym-id CartPole-v1
# atari
poetry install -E atari
python cleanrl/dqn_atari.py --gym-id BreakoutNoFrameskip-v4
python cleanrl/c51_atari.py --gym-id BreakoutNoFrameskip-v4
python cleanrl/ppo_atari.py --gym-id BreakoutNoFrameskip-v4
python cleanrl/apex_dqn_atari.py --gym-id BreakoutNoFrameskip-v4
# NEW: 3-4x side-effects free speed up with envpool's atari (only available to linux)
poetry install -E envpool
python cleanrl/ppo_atari_envpool.py --gym-id BreakoutNoFrameskip-v4
# Learn Pong-v5 in ~5-10 mins
# Side effects such as lower sample efficiency might occur
poetry run python ppo_atari_envpool.py --clip-coef=0.2 --num-envs=16 --num-minibatches=8 --num-steps=128 --update-epochs=3
# pybullet
poetry install -E pybullet
python cleanrl/td3_continuous_action.py --gym-id MinitaurBulletDuckEnv-v0
python cleanrl/ddpg_continuous_action.py --gym-id MinitaurBulletDuckEnv-v0
python cleanrl/sac_continuous_action.py --gym-id MinitaurBulletDuckEnv-v0
# procgen
poetry install -E procgen
python cleanrl/ppo_procgen.py --gym-id starpilot
python cleanrl/ppg_procgen.py --gym-id starpilot
# ppo + lstm
python cleanrl/ppo_atari_lstm.py --gym-id BreakoutNoFrameskip-v4
python cleanrl/ppo_memory_env_lstm.py
You may also use a prebuilt development environment hosted in Gitpod:
- Deep Q-Learning (DQN)
- Categorical DQN (C51)
- Proximal Policy Gradient (PPO)
- Soft Actor Critic (SAC)
- Deep Deterministic Policy Gradient (DDPG)
- Twin Delayed Deep Deterministic Policy Gradient (TD3)
- Apex Deep Q-Learning (Apex-DQN)
CleanRL has a sub project called Open RL Benchmark (https://benchmark.cleanrl.dev/), where we have tracked thousands of experiments across domains. The benchmark is interactive, and researchers can easily query information such as GPU utilization and videos of an agent's gameplay that are normally hard to acquire in other RL benchmarks. Here are some screenshots.
We have a Discord Community for support. Feel free to ask questions. Posting in Github Issues and PRs are also welcome. Also our past video recordings are available at YouTube
If you use CleanRL in your work, please cite our technical paper:
@article{huang2021cleanrl,
title={CleanRL: High-quality Single-file Implementations of Deep Reinforcement Learning Algorithms},
author={Shengyi Huang and Rousslan Fernand Julien Dossa and Chang Ye and Jeff Braga},
year={2021},
eprint={2111.08819},
archivePrefix={arXiv},
primaryClass={cs.LG}
}