Repository files navigation

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 variant is put into a single standalone file.
  • For example, ourppo_atari.py only has 340 lines of code but contains all implementation details on how PPO works with Atari games,so it is a great reference implementation to read for folks who do not wish to read an entire modular library.
• 📊 Benchmarked Implementation (7+ algorithms and 34+ games athttps://benchmark.cleanrl.dev)
• 📈 Tensorboard Logging
• 🪛 Local Reproducibility via Seeding
• 🎮 Videos of Gameplay Capturing
• 🧫 Experiment Management withWeights and Biases
• 💸 Cloud Integration with docker and AWS

You can read more about CleanRL in ourJMLR paper anddocumentation.

Notable CleanRL-related projects:

• corl-team/CORL: Offline RL algorithm implemented in CleanRL style
• pytorch-labs/LeanRL: Fast optimized PyTorch implementation of CleanRL RL algorithms using CUDAGraphs.

ℹ️Support for Gymnasium:Farama-Foundation/Gymnasium is the next generation ofopenai/gym that will continue to be maintained and introduce new features. Please see theirannouncement for further detail. We are migrating togymnasium and the progress can be tracked invwxyzjn/cleanrl#277.

⚠️NOTE: CleanRL isnot a modular library and therefore it is not meant to be imported. At the cost of duplicate code, we make all implementation details of a DRL algorithm variant easy to understand, so CleanRL comes with its own pros and cons. You should consider using CleanRL if you want to 1) understand all implementation details of an algorithm's variant or 2) prototype advanced features that other modular DRL libraries do not support (CleanRL has minimal lines of code so it gives you great debugging experience and you don't have do a lot of subclassing like sometimes in modular DRL libraries).

Prerequisites:

• Python >=3.7.1,<3.11
• Poetry 1.2.1+

To run experiments locally, give the following a try:

git clone https://github.com/vwxyzjn/cleanrl.git&&cd cleanrlpoetry install# alternatively, you could use `poetry shell` and do# `python run cleanrl/ppo.py`poetry run python cleanrl/ppo.py \    --seed 1 \    --env-id CartPole-v0 \    --total-timesteps 50000# open another terminal and enter `cd cleanrl/cleanrl`tensorboard --logdir runs

To use experiment tracking with wandb, run

wandb login# only required for the first timepoetry run python cleanrl/ppo.py \    --seed 1 \    --env-id CartPole-v0 \    --total-timesteps 50000 \    --track \    --wandb-project-name cleanrltest

If you are not usingpoetry, you can install CleanRL withrequirements.txt:

# core dependenciespip install -r requirements/requirements.txt# optional dependenciespip install -r requirements/requirements-atari.txtpip install -r requirements/requirements-mujoco.txtpip install -r requirements/requirements-mujoco_py.txtpip install -r requirements/requirements-procgen.txtpip install -r requirements/requirements-envpool.txtpip install -r requirements/requirements-pettingzoo.txtpip install -r requirements/requirements-jax.txtpip install -r requirements/requirements-docs.txtpip install -r requirements/requirements-cloud.txtpip install -r requirements/requirements-memory_gym.txt

To run training scripts in other games:

poetry shell# classic controlpython cleanrl/dqn.py --env-id CartPole-v1python cleanrl/ppo.py --env-id CartPole-v1python cleanrl/c51.py --env-id CartPole-v1# ataripoetry install -E ataripython cleanrl/dqn_atari.py --env-id BreakoutNoFrameskip-v4python cleanrl/c51_atari.py --env-id BreakoutNoFrameskip-v4python cleanrl/ppo_atari.py --env-id BreakoutNoFrameskip-v4python cleanrl/sac_atari.py --env-id BreakoutNoFrameskip-v4# NEW: 3-4x side-effects free speed up with envpool's atari (only available to linux)poetry install -E envpoolpython cleanrl/ppo_atari_envpool.py --env-id BreakoutNoFrameskip-v4# Learn Pong-v5 in ~5-10 mins# Side effects such as lower sample efficiency might occurpoetry run python ppo_atari_envpool.py --clip-coef=0.2 --num-envs=16 --num-minibatches=8 --num-steps=128 --update-epochs=3# procgenpoetry install -E procgenpython cleanrl/ppo_procgen.py --env-id starpilotpython cleanrl/ppg_procgen.py --env-id starpilot# ppo + lstmpoetry install -E ataripython cleanrl/ppo_atari_lstm.py --env-id BreakoutNoFrameskip-v4

You may also use a prebuilt development environment hosted in Gitpod:

To make our experimental data transparent, CleanRL participates in a related project calledOpen RL Benchmark, which contains tracked experiments from popular DRL libraries such as ours,Stable-baselines3,openai/baselines,jaxrl, and others.

Check outhttps://benchmark.cleanrl.dev/ for a collection of Weights and Biases reports showcasing tracked DRL experiments. The reports are 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. In the future, Open RL Benchmark will likely provide an dataset API for researchers to easily access the data (seerepo).

We have aDiscord Community for support. Feel free to ask questions. Posting inGithub Issues and PRs are also welcome. Also our past video recordings are available atYouTube

If you use CleanRL in your work, please cite our technicalpaper:

@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: High-quality Single-file Implementations of Deep Reinforcement Learning Algorithms},journal ={Journal of Machine Learning Research},year    ={2022},volume  ={23},number  ={274},pages   ={1--18},url     ={http://jmlr.org/papers/v23/21-1342.html}}

CleanRL is a community-powered by project and our contributors run experiments on a variety of hardware.

• We thank many contributors for using their own computers to run experiments
• We thank Google'sTPU research cloud for providing TPU resources.
• We thankHugging Face's cluster for providing GPU resources.