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
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).fixUpgrade 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).fixAlways 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`.fixImport `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.fixEnsure 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.fixIf 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.