Install & Compatibility
Where this runs
tested against v2.9.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
✓ 85.05s
py 3.11
✕ build_error
✓ 80.45s
py 3.12
✕ build_error
✓ 70.8s
py 3.13
✕ build_error
✓ 65.5s
py 3.9
✕ build_error
✕ timeout
5299MB installed
● package 5299MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PPO
✓ from stable_baselines3 import PPO
A2C
✓ from stable_baselines3 import A2C
SAC
✓ from stable_baselines3 import SAC
DQN
✓ from stable_baselines3 import DQN
make_vec_env
✓ from stable_baselines3.common.env_util import make_vec_env
evaluate_policy
✓ from stable_baselines3.common.evaluation import evaluate_policy
This quickstart demonstrates how to create a Gymnasium environment, instantiate an A2C agent, train it for a specified number of timesteps, save and load the trained model, and finally evaluate its performance.
import gymnasium as gym
from stable_baselines3 import A2C
# Create environment
env = gym.make("CartPole-v1")
# Instantiate the agent
model = A2C("MlpPolicy", env, verbose=1)
# Train the agent
model.learn(total_timesteps=10000)
# Save the model
model.save("a2c_cartpole")
# Delete model and reload it to demonstrate saving and loading
del model
model = A2C.load("a2c_cartpole")
# Evaluate the trained agent
obs, info = env.reset()
for i in range(1000):
action, _states = model.predict(obs, deterministic=True)
obs, reward, terminated, truncated, info = env.step(action)
if terminated or truncated:
obs, info = env.reset()
env.close()
Debug
Known issues
breakingDropped Python 3.9 support in v2.8.0. Users on Python 3.9 must upgrade to Python >= 3.10. Similarly, Python 3.8 support was removed in v2.5.0/v2.4.0.fixUpgrade your Python environment to version 3.10 or higher.
affects: >=2.8.0 (for Python 3.9), >=2.5.0 (for Python 3.8)
breakingThe minimum required PyTorch version increased to 2.3.0 in Stable Baselines3 v2.5.0. Ensure your PyTorch installation meets this requirement.fixUpgrade PyTorch to version 2.3.0 or newer (e.g., `pip install torch>=2.3.0`).
affects: >=2.5.0
breakingStable Baselines3 switched to Gymnasium as its primary environment backend starting from v2.0.0. While compatibility layers exist via `shimmy` for older `gym` environments, direct migration to Gymnasium is highly recommended.fixReplace `import gym` with `import gymnasium as gym` and update environment creation where necessary. Install `shimmy` if you need to wrap legacy Gym environments.
affects: >=2.0.0
breakingStable Baselines3 v2.3.0 introduced a breaking change where `torch.load()` was called with `weights_only=True`, causing issues when loading policies trained with PyTorch 1.13. This was reverted in v2.3.2.fixUpgrade Stable Baselines3 to v2.3.2 or newer if you encounter loading issues with PyTorch 1.13.
affects: 2.3.0, 2.3.1
breakingStarting from v2.8.0, `strict=True` is now set for every call to `zip(...)` internally, which can raise `ValueError` if iterables have different lengths. This change also applies to `sb3_contrib` (v2.6.0).fixEnsure that any iterables passed to internal `zip` operations (or `zip` calls within custom code interacting with SB3) have consistent lengths.
affects: >=2.8.0 (SB3), >=2.6.0 (SB3-Contrib)
gotchaWhen using custom callbacks, ensure they return a boolean (`True` to continue, `False` to stop training). Returning `None` will be interpreted as `False` and abruptly stop training since `stable-baselines3-contrib` v2.6.0 (which impacts SB3).fixReview custom callbacks to explicitly return `True` or `False` to control training flow.
affects: >=2.6.0 (SB3-Contrib, affecting SB3 users of custom callbacks)
gotchaFor accurate evaluation results, especially when other wrappers modify rewards or episode lengths (e.g., reward scaling), it is recommended to wrap your environment with the `Monitor` wrapper before any other wrappers.fixWrap your environment with `Monitor` early in the environment stacking process: `env = Monitor(env)`.
affects: All versions
Upgrade
Version history
2.9.0latest on PyPI · released Jun 15, 2026
Audit
Dependencies
pythonrequiredStable Baselines3 v2.8.0 requires Python 3.10 or newer. Support for Python 3.9 was dropped in v2.8.0, and 3.8 in v2.5.0.
torchrequiredThe library is built on PyTorch. A minimum version of 2.3.0 is required since SB3 v2.5.0.
gymnasiumrequiredGymnasium is the primary environment backend since SB3 v2.0.0. While older gym versions might be compatible via `shimmy`, direct use of Gymnasium is recommended.