stable-baselines3 README

The project's README from github.com/DLR-RM/stable-baselines3. As one markdown file: README.md.

CI Documentation Status coverage report codestyle

Stable Baselines3

Stable Baselines3 (SB3) is a set of reliable implementations of reinforcement learning algorithms in PyTorch. It is the next major version of Stable Baselines.

You can read a detailed presentation of Stable Baselines3 in the v1.0 blog post or our JMLR paper.

These algorithms will make it easier for the research community and industry to replicate, refine, and identify new ideas, and will create good baselines to build projects on top of. We expect these tools will be used as a base around which new ideas can be added, and as a tool for comparing a new approach against existing ones. We also hope that the simplicity of these tools will allow beginners to experiment with a more advanced toolset, without being buried in implementation details.

Note: Despite its simplicity of use, Stable Baselines3 (SB3) assumes you have some knowledge about Reinforcement Learning (RL). You should not utilize this library without some practice. To that extent, we provide good resources in the documentation to get started with RL.

Main Features

The performance of each algorithm was tested (see Results section in their respective page). You can take a look at the issues #48 and #49 for more details.

We also provide detailed logs and reports on the OpenRL Benchmark platform.

Features Stable-Baselines3
State of the art RL methods :heavy_check_mark:
Documentation :heavy_check_mark:
Custom environments :heavy_check_mark:
Custom policies :heavy_check_mark:
Common interface :heavy_check_mark:
Dict observation space support :heavy_check_mark:
Ipython / Notebook friendly :heavy_check_mark:
Tensorboard support :heavy_check_mark:
PEP8 code style :heavy_check_mark:
Custom callback :heavy_check_mark:
High code coverage :heavy_check_mark:
Type hints :heavy_check_mark:

Planned features

Since most of the features from the original roadmap have been implemented, there are no major changes planned for SB3; it is now stable. If you want to contribute, you can search in the issues for the ones where help is welcomed and the other proposed enhancements.

While SB3 development is now focused on bug fixes and maintenance (doc update, user experience, ...), there is more active development going on in the associated repositories:

Migration guide: from Stable-Baselines (SB2) to Stable-Baselines3 (SB3)

A migration guide from SB2 to SB3 can be found in the documentation.

Documentation

Documentation is available online: https://stable-baselines3.readthedocs.io/

Integrations

Stable-Baselines3 has some integration with other libraries/services like Weights & Biases for experiment tracking or Hugging Face for storing/sharing trained models. You can find out more in the dedicated section of the documentation.

RL Baselines3 Zoo: A Training Framework for Stable Baselines3 Reinforcement Learning Agents

RL Baselines3 Zoo is a training framework for Reinforcement Learning (RL).

It provides scripts for training, evaluating agents, tuning hyperparameters, plotting results and recording videos.

In addition, it includes a collection of tuned hyperparameters for common environments and RL algorithms, and agents trained with those settings.

Goals of this repository:

  1. Provide a simple interface to train and enjoy RL agents
  2. Benchmark the different Reinforcement Learning algorithms
  3. Provide tuned hyperparameters for each environment and RL algorithm
  4. Have fun with the trained agents!

Github repo: https://github.com/DLR-RM/rl-baselines3-zoo

Documentation: https://rl-baselines3-zoo.readthedocs.io/en/master/

SB3-Contrib: Experimental RL Features

We implement experimental features in a separate contrib repository: SB3-Contrib

This allows SB3 to maintain a stable and compact core, while still providing the latest features, like Recurrent PPO (PPO LSTM), CrossQ, Truncated Quantile Critics (TQC), Quantile Regression DQN (QR-DQN) or PPO with invalid action masking (Maskable PPO).

Documentation is available online: https://sb3-contrib.readthedocs.io/

Stable-Baselines Jax (SBX)

Stable Baselines Jax (SBX) is a proof of concept version of Stable-Baselines3 in Jax, with recent algorithms like DroQ or CrossQ.

It provides a minimal number of features compared to SB3 but can be much faster (up to 20x times!): https://twitter.com/araffin2/status/1590714558628253698

Installation

Note: Stable-Baselines3 supports PyTorch >= 2.8

Prerequisites

Stable Baselines3 requires Python 3.10+.

Windows

To install stable-baselines on Windows, please look at the documentation.

Install using pip

Install the Stable Baselines3 package:

pip install 'stable-baselines3[extra]'

This includes optional dependencies like Tensorboard, OpenCV, ale-py to train on atari games, as well as pandas and matplotlib for plotting and analyzing results. If you do not need those, you can use:

pip install stable-baselines3

Please read the documentation for more details and alternatives (from source, using docker).

Example

Most of the code in the library tries to follow a sklearn-like syntax for the Reinforcement Learning algorithms.

Here is a quick example of how to train and run PPO on a cartpole environment:

import gymnasium as gym

from stable_baselines3 import PPO

env = gym.make("CartPole-v1", render_mode="human")

model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=10_000)

vec_env = model.get_env()
obs = vec_env.reset()
for i in range(1000):
    actions, _states = model.predict(obs, deterministic=True)
    obs, rewards, dones, info = vec_env.step(actions)
    vec_env.render()
    # VecEnv resets automatically
    # if done:
    #   obs = env.reset()

env.close()

Or just train a model with a one liner if the environment is registered in Gymnasium and if the policy is registered:

from stable_baselines3 import PPO

model = PPO("MlpPolicy", "CartPole-v1").learn(10_000)

Please read the documentation for more examples.

Try it online with Colab Notebooks!

All the following examples can be executed online using Google Colab notebooks:

Implemented Algorithms

Name Recurrent Box Discrete MultiDiscrete MultiBinary Multi Processing
A2C :x: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark:
ARS1 :x: :heavy_check_mark: :heavy_check_mark: :x: :x: :heavy_check_mark:
CrossQ12 :x: :heavy_check_mark: :x: :x: :x: :heavy_check_mark:
DDPG :x: :heavy_check_mark: :x: :x: :x: :heavy_check_mark:
DQN :x: :x: :heavy_check_mark: :x: :x: :heavy_check_mark:
DroQ2 :x: :heavy_check_mark: :x: :x: :x: :heavy_check_mark:
HER :x: :heavy_check_mark: :heavy_check_mark: :x: :x: :heavy_check_mark:
Maskable PPO1 :x: :x: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark:
PPO :x: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark:
QR-DQN1 :x: :x: :heavy_check_mark: :x: :x: :heavy_check_mark:
RecurrentPPO1 :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark:
SAC :x: :heavy_check_mark: :x: :x: :x: :heavy_check_mark:
SAC-N2 :x: :heavy_check_mark: :x: :x: :x: :heavy_check_mark:
SimBa2 :x: :heavy_check_mark: :x: :x: :x: :heavy_check_mark:
TD3 :x: :heavy_check_mark: :x: :x: :x: :heavy_check_mark:
TQC1 :x: :heavy_check_mark: :x: :x: :x: :heavy_check_mark:
TRPO1 :x: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark:

1: Implemented in SB3 Contrib GitHub repository.

2: Implemented in SBX (SB3 + Jax)

Actions gymnasium.spaces:

Testing the installation

Install dependencies

pip install -e '.[docs,tests,extra]'

Run tests

All unit tests in stable baselines3 can be run using pytest runner:

make pytest

To run a single test file:

python3 -m pytest -v tests/test_env_checker.py

To run a single test:

python3 -m pytest -v -k 'test_check_env_dict_action'

You can also do a static type check using mypy:

pip install mypy
make type

Codestyle check with ruff:

pip install ruff
make lint

Projects Using Stable-Baselines3

We try to maintain a list of projects using stable-baselines3 in the documentation, please tell us if you want your project to appear on this page ;)

Citing the Project

To cite this repository in publications:

@article{stable-baselines3,
  author  = {Antonin Raffin and Ashley Hill and Adam Gleave and Anssi Kanervisto and Maximilian Ernestus and Noah Dormann},
  title   = {Stable-Baselines3: Reliable Reinforcement Learning Implementations},
  journal = {Journal of Machine Learning Research},
  year    = {2021},
  volume  = {22},
  number  = {268},
  pages   = {1-8},
  url     = {https://jmlr.org/papers/v22/20-1364.html}
}

Note: If you need to refer to a specific version of SB3, you can also use the Zenodo DOI.

Maintainers

Stable-Baselines3 is currently maintained by Ashley Hill (aka @hill-a), Antonin Raffin (aka @araffin), Maximilian Ernestus (aka @ernestum), Adam Gleave (@AdamGleave), Anssi Kanervisto (@Miffyli) and Quentin Gallouédec (@qgallouedec).

Important Note: We do not provide technical support, or consulting and do not answer personal questions via email. Please post your question on the RL Discord, Reddit, or Stack Overflow in that case.

How To Contribute

For anyone interested in making the baselines better, there is still some documentation that needs to be done. If you want to contribute, please read CONTRIBUTING.md guide first.

Acknowledgments

The initial work to develop Stable Baselines3 was partially funded by the project Reduced Complexity Models from the Helmholtz-Gemeinschaft Deutscher Forschungszentren, and by the EU Horizon 2020 Research and Innovation Programme under grant number 951992 (VeriDream).

The original version, Stable Baselines, was created in the robotics lab U2IS (INRIA Flowers team) at ENSTA ParisTech.

Logo credits: L.M. Tenkes

stable-baselines3 (DLR-RM/stable-baselines3)

Searching Database…

13.9K ·GitHub
Stable-baselines3
这是什么？Stable Baselines3（SB3）是一组可靠的 PyTorch 强化学习算法实现，旨在作为科研和工业项目的扎实基线。
这是框架，还是算法实现的库？这是一个库：你导入 PPO、SAC、DQN 等算法类，然后用类似 sklearn 的写法，针对你的环境调用它们，而不是在框架里搭建你的应用。
我该怎么安装和运行它？通过 pip 安装（`pip install stable-baselines3[extra]` 会安装包含 Tensorboard、OpenCV、ale-py 等在内的完整版本；不加额外依赖则为最小安装），然后用几行代码，针对 Gymnasium 环境训练 PPO 等算法。
用之前我需要准备什么？Python 3.10+ 和 PyTorch 2.8 或更高版本；Windows 安装需要文档中说明的额外步骤。
完全不懂强化学习的新手，能直接上手用吗？不能。维护者明确提醒，尽管 SB3 的 API 很简单，你仍需要一定的强化学习基础知识，才能正确使用它。
它在 Windows 上也能跑吗，还是只能在 Linux/macOS 上？可以。它是纯 Python/PyTorch 库，可跨平台运行，不过 Windows 安装有其单独的文档步骤。
SB3 开箱即用地实现了哪些算法？A2C、PPO、DQN、DDPG、SAC、TD3、ARS、HER 等，支持 Box、Discrete、MultiDiscrete 和 MultiBinary 动作空间，并支持多进程。
SB3-Contrib 是什么？一个配套仓库，收录实验性或较新的算法，如 Recurrent PPO、CrossQ、TQC、QR-DQN 和 Maskable PPO。它与 SB3 核心分开维护，使核心保持稳定和精简。
RL Baselines3 Zoo 是什么？一个基于 SB3 构建的训练框架，提供训练、评估、超参数调优、绘图和录制视频的脚本，并附带针对每个环境和算法调好的超参数集合。
SBX 是什么？我为什么要用它？SBX（Stable Baselines Jax）是 SB3 在 Jax 上的概念验证性重新实现。它支持的功能较少，但运行速度最高可快 20 倍，并包括 DroQ、CrossQ 等较新的算法。
What are similar projects?Gymnasium, cleanrl, baselines, starVLA, lerobot, wandb, FluxVLA, handson-ml3
Which topics is it in?gym, toolbox, algorithm, tensorflow, robotics, reinforcement-learning, neural-network, ci, pytorch, benchmark, openai, deep-learning
Creator
DLR-RM
Size
5.3 MB
Stars
13.9K
Updated
CommitOct 13Releasev2.9.0Jun 15
Age
6y
Commits · 90 Days