Registry / ai-ml / sb3-contrib

sb3-contrib

JSON →
library2.8.0pypypiunverified

sb3-contrib is the experimental contribution package for Stable Baselines3, providing additional reinforcement learning algorithms and features not yet integrated into the main SB3 library. It is currently at version 2.8.0 and typically releases new versions in sync with Stable Baselines3's major and minor updates, often introducing breaking changes related to Python or SB3 dependency versions.

pip install sb3-contrib stable-baselines3 gymnasium
INSTALL
IMPORT
SIG · SB3-CONTRIB
S
sb3-contrib
ai-mlpythonv2.8.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
3/4 runs
py 3.11
✕ build_error
3/4 runs
py 3.12
✕ build_error
3/4 runs
py 3.13
✕ build_error
3/4 runs
py 3.9
✕ build_error
✕ timeout
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MaskablePPO
from sb3_contrib import MaskablePPO
RecurrentPPO
from sb3_contrib import RecurrentPPO
ARS
from sb3_contrib import ARS
TRPO
from sb3_contrib import TRPO
CrossQ
from sb3_contrib import CrossQ
QRDQN
from stable_baselines3 import QRDQN
from sb3_contrib import QRDQN
QRDQN was moved from sb3-contrib to stable_baselines3 core in SB3 v2.0.

This quickstart demonstrates how to set up a vectorized Gymnasium environment and train an ARS (Augmented Random Search) agent from sb3-contrib. It covers environment creation, model initialization, training, and basic evaluation.

import gymnasium as gym from sb3_contrib import ARS from stable_baselines3.common.env_util import make_vec_env from stable_baselines3.common.vec_env import VecMonitor # 1. Create a vectorized environment env_id = "CartPole-v1" vec_env = make_vec_env(env_id, n_envs=4, seed=0) vec_env = VecMonitor(vec_env) # Recommended wrapper for logging # 2. Initialize the ARS agent # ARS (Augmented Random Search) is a policy-gradient-free algorithm model = ARS("MlpPolicy", vec_env, verbose=1) # 3. Train the agent print("Training the ARS model...") model.learn(total_timesteps=10000) print("Training finished.") # 4. Save and load the model (optional) model.save("ars_cartpole") del model # remove to demonstrate loading model = ARS.load("ars_cartpole") # 5. Evaluate the trained agent print("Evaluating the trained model...") obs, info = vec_env.reset() for _ in range(100): # Run for 100 steps action, _states = model.predict(obs, deterministic=True) obs, rewards, dones, infos = vec_env.step(action) # Handle episode termination for vectorized environments for i, done in enumerate(dones): if done: print(f"Episode finished, reward: {infos[i]['episode']['r']:.2f}") vec_env.close()
Debug
Known issues
breakingPython 3.9 support was removed in v2.8.0. Earlier versions (v2.5.0, v2.1.0) dropped support for Python 3.8 and 3.7 respectively. Ensure your Python version meets the minimum requirement (>=3.10 for v2.8.0).
fix
Upgrade your Python environment to 3.10 or later. For example, use pyenv or update your Conda environment.
affects: >=2.1.0
breakingsb3-contrib is tightly coupled with `stable-baselines3`. New versions of `sb3-contrib` frequently require specific, often newer, versions of `stable-baselines3` (e.g., v2.8.0 requires SB3 >= 2.8.0).
fix
Always install/upgrade both packages together: `pip install --upgrade stable-baselines3 sb3-contrib`.
affects: All versions
gotchaThe `QRDQN` algorithm was originally in `sb3-contrib` but was moved to the core `stable_baselines3` library starting with SB3 v2.0. Attempting to import it from `sb3_contrib` will result in an `ImportError`.
fix
Import `QRDQN` from `stable_baselines3`: `from stable_baselines3 import QRDQN`.
affects: stable-baselines3 >= 2.0.0
gotchaAlgorithms like `MaskablePPO` and `RecurrentPPO` require the environment to implement an `action_masks()` method, which returns a boolean numpy array indicating valid actions. This is not a standard `gymnasium.Env` or `VecEnv` feature.
fix
Ensure your custom environment or a wrapper implements `action_masks()`. When using `model.predict()`, pass the masks explicitly: `model.predict(obs, action_masks=env.action_masks())`.
affects: All versions
breakingThe default `learning_starts` parameter for `QRDQN` was significantly changed in `sb3-contrib` v2.3.0 (from 50_000 to 100) to align with other off-policy algorithms. This can drastically alter training behavior if not explicitly set.
fix
If migrating from older versions, explicitly set `learning_starts` to 50_000 for `QRDQN` if you want the old behavior, or adapt your hyperparameter tuning to the new default.
affects: >=2.3.0
Upgrade
Version history
2.8.0latest on PyPI · released Apr 1, 2026
Audit
Dependencies
stable-baselines3requiredCore dependency; sb3-contrib algorithms extend stable-baselines3.
gymnasiumoptionalStandard environment interface for training RL agents.
torchrequiredUnderlying deep learning framework used by Stable Baselines3.
Agent activity
14 hits · last 30 days
node
12
OpenAI (training)
1
Resources