Stable-Baselines3 安装完全指南从 PyPI 到 Docker 的全场景部署手册【免费下载链接】stable-baselines3PyTorch version of Stable Baselines, reliable implementations of reinforcement learning algorithms.项目地址: https://gitcode.com/GitHub_Trending/st/stable-baselines3Stable-Baselines3下文简称 SB3是当前仓库中基于 PyTorch 的强化学习算法库版本 2.9.0提供了 PPO、DQN、SAC、TD3、A2C、DDPG 等可靠实现。本文以仓库官方安装文档 docs/guide/install.md 为骨架结合 setup.py、Dockerfile 与 scripts 目录下的构建脚本系统讲解从 pip 一键安装、源码开发安装到 Docker 容器化部署的全部路径帮助你根据自己的硬件、网络与开发需求选择最合适的安装方案并彻底解决安装过程中的常见坑。安装前置条件Python 3.10 与 PyTorch 2.8官方安装文档明确要求Python 3.10 及以上版本PyTorch 2.8。这一约束在仓库的打包配置中有更精细的落地在 setup.py 中python_requires3.10同时install_requires声明的核心运行依赖为依赖包版本约束用途gymnasium0.29.1,2.0环境接口标准Gym 的继承者numpy1.20,3.0数值计算基础torch2.8,3.0深度学习后端cloudpickle无版本上限模型的序列化与保存见 common/save_util.py也就是说PyTorch 的安装需要由你自己先完成可通过 pip 或 conda 安装 CPU/GPU 版本SB3 的 pip 安装会自动拉取其余依赖。请确保 Python 版本 3.10否则 pip 会直接拒绝安装。Windows 用户推荐 miniforge官方文档建议 Windows 用户使用miniforgeconda-forge 的轻量发行版来管理 Python 环境因为它能更简单地安装 Python 包和所需的本地库。你需要创建一个 Python 3.10 或以上的环境例如conda create -n sb3 python3.12 conda activate sb3创建好环境后可以直接进入下一步安装 Stable-Baselines3无需额外配置。稳定版安装一行命令从 PyPI 获取正式发布版对绝大多数使用者来说直接安装 PyPI 上的稳定发布版是最省心的方式。官方文档提供了两种安装粒度。最小安装如果只需要核心算法库不涉及 Atari 游戏、TensorBoard 可视化等附加能力pip install stable-baselines3该命令只安装install_requires中的四项核心依赖gymnasium、numpy、torch、cloudpickle占用空间最小。完整安装推荐含可选依赖pip install stable-baselines3[extra]注意Zsh 等部分 shell 需要对方括号加引号否则会报 zsh: no matches found 之类的错误因此官方命令特意写成stable-baselines3[extra]。[extra]会安装 setup.py 中extras_require定义的可选依赖它们分别服务于训练可视化、渲染、Atari 游戏等场景extra 组包含包用途extraopencv-python视频渲染录制环境画面pygame-ce环境交互渲染后端tensorboard2.9.1TensorBoard 训练日志可视化见 guide/tensorboard.mdpsutil检查回放缓冲区replay buffer内存占用tqdm、rich训练进度条回调common/callbacks.py 中的ProgressBarCallbackale-py0.9.0、pillow创建 Atari 游戏环境pandas、matplotlib结果绘图与加载common/results_plotter.py一句话总结日常强化学习训练装[extra]就够了它覆盖了 TensorBoard、OpenCV 渲染和 Atari 游戏三大高频需求。验证安装是否成功安装完成后可以在 Python 中做一次快速冒烟验证以 PPO 在 CartPole 上训练为例代码取自 setup.py 内置的快速示例import gymnasium from stable_baselines3 import PPO model PPO(MlpPolicy, CartPole-v1, verbose1) model.learn(total_timesteps10_000)也可以打印系统信息确认环境与版本from stable_baselines3.common.utils import get_system_info print(get_system_info())get_system_info定义在 common/utils.py会输出 Python、PyTorch、gymnasium 的版本以及 CPU/GPU 信息是排查环境问题的第一手工具。当前仓库的版本号记录在 stable_baselines3/version.txt内容为2.9.0并通过 stable_baselines3/init.py 暴露为stable_baselines3.__version__。安装每日最新开发版Bleeding-edge如果你想第一时间用到 master 分支上的新特性尚未发布到 PyPI官方文档提供了直接从 Git 仓库安装的方式pip install githttps://github.com/DLR-RM/stable-baselines3带全部可选依赖的安装命令为pip install stable_baselines3[extra,tests,docs] githttps://github.com/DLR-RM/stable-baselines3其中[tests,docs]对应 setup.py 中extras_require的另外两组依赖tests组pytest、pytest-cov、pytest-env、pytest-xdist测试与覆盖率、mypy1.9.0,2类型检查、ruff0.5.6lint 与 import 排序、black26.1.0,27代码格式化docs组sphinx5,10、sphinx-autobuild、sphinx-rtd-theme3.0.0、sphinxcontrib.spelling、sphinx_copybutton、myst-parser4,6构建本文档所在的 Sphinx 站点配置见 docs/conf.py。需要注意的是直接pip install git...每次拉取的都是 master 最新状态不保证与文档描述完全同步适合尝鲜者追求稳定请使用上一节的 PyPI 发布版。开发版安装以贡献者身份搭建可编辑环境如果你打算向 SB3 提交代码、运行测试并构建文档官方文档推荐「克隆仓库 可编辑安装」的方式git clone https://github.com/DLR-RM/stable-baselines3 cd stable-baselines3 pip install -e .[docs,tests,extra]-eeditable使安装指向本地源码目录改动代码后立即生效无需重新安装同时安装docs、tests、extra三组依赖覆盖文档构建、测试运行与可视化渲染的全部需求。运行测试仓库根目录 Makefile 提供了便捷入口make pytest会调用 scripts/run_tests.sh./scripts/run_tests.sh该脚本实际执行python3 -m pytest --cov-report html --cov-report term --cov. -v --coloryes -m not expensive --durations15即运行标记为not expensive的测试expensive标记在 pyproject.toml 中定义可用-m not expensive排除耗时的用例同时输出 HTML 与终端覆盖率报告。整个测试集分布在 tests 目录下覆盖缓冲区、回调、向量环境、策略网络等核心模块。构建文档本地构建本项目文档本文所依赖的 Sphinx 站点make doc它会进入 docs 目录执行make htmldocs/Makefile 中SPHINXOPTS -W会把文档警告视为错误保证输出质量。此外make lint、make format、make type分别对应 ruff 代码检查、black 格式化与 mypy 类型检查可用于提交前的自检。conda 环境替代方案仓库 docs/conda_env.yml 提供了一份完整的 conda 环境定义一次性搞定 Python、PyTorch CPU 版与全部文档/运行依赖name: root channels: - conda-forge dependencies: - pip26.1.2 - python3.12 - pytorch-cpu2.9.1 - pip: - gymnasium0.29.1,2.0 - cloudpickle - opencv-python-headless - pandas - numpy1.20,3.0 - matplotlib - sphinx5,10 - sphinx_rtd_theme3.0 - sphinx_copybutton - myst-parser4,6使用方式conda env create -f docs/conda_env.yml conda activate root注意其中 PyTorch 为CPU 版本pytorch-cpu且 OpenCV 直接选用opencv-python-headless——这是专为无图形界面环境服务器、容器准备的渲染方案。使用 Docker 镜像开箱即用的标准环境如果不想在宿主机折腾 Python 环境官方文档推荐两条 Docker 路线。优先推荐RL Baselines3 Zoo 的预装镜像如果你需要「SB3 已装好」的现成镜像官方推荐使用 RL Baselines3 Zoo 项目提供的镜像它内置了 SB3 以及训练、评估所需的全套工具链。官方开发镜像拉取即用当前仓库Dockerfile构建的镜像包含 SB3 的全部依赖但不包含 SB3 包本身其定位是开发环境——通过 bind mount 把本地源码挂进容器使用。GPU 镜像需要支持 NVIDIA GPU 的 Docker 运行时docker pull stablebaselines/stable-baselines3纯 CPU 镜像docker pull stablebaselines/stable-baselines3-cpu自行构建镜像在仓库根目录执行make docker-gpu # 构建 GPU 镜像等价于 USE_GPUTrue ./scripts/build_docker.sh make docker-cpu # 构建 CPU 镜像构建脚本 scripts/build_docker.sh 的关键细节基础镜像CPU 版基于mambaorg/micromamba:2.0-ubuntu24.04GPU 版基于mambaorg/micromamba:2.0-cuda12.6.3-ubuntu24.04CUDA 12.6.3PyTorch 源CPU 版使用https://download.pytorch.org/whl/cpuGPU 版使用https://download.pytorch.org/whl/cu126CUDA 12.6 专用 wheel版本标签镜像被同时打上stablebaselines/stable-baselines3:版本号版本号读取自 stable_baselines3/version.txt当前为 2.9.0和:latest两个标签发布若设置环境变量RELEASETrue构建完成后会自动docker push推送镜像依赖安装Dockerfile 内部通过 micromamba 创建 Python 3.12 环境再用uv安装torch与.[extra,tests,docs]最后将opencv-python替换为opencv-python-headless容器内通常没有 X server详见下文问题排查一节。如果你处于代理环境构建时需向docker build传递额外参数--networkhost --build-arg HTTPS_PROXYhttps://your.proxy.fr:8080/ --build-arg https_proxyhttps://your.proxy.fr:8080/运行容器跑测试CPU/GPU直接运行 docker runGPUnvidia-docker 旧式写法docker run -it --runtimenvidia --rm --network host --ipchost --name test \ --mount src$(pwd),target/home/mamba/stable-baselines3,typebind \ stablebaselines/stable-baselines3 bash -c cd /home/mamba/stable-baselines3/ pytest tests/更推荐的做法是使用仓库自带的封装脚本内部已处理挂载与工作目录切换./scripts/run_docker_gpu.sh pytest tests/ # GPU 版 ./scripts/run_docker_cpu.sh pytest tests/ # CPU 版两个脚本scripts/run_docker_gpu.sh、scripts/run_docker_cpu.sh会把当前目录$(pwd)以 bind mount 方式挂载到容器内/home/mamba/stable-baselines3然后在容器内cd到该目录并执行你传入的任意命令——所以你可以传入pytest tests/、make lint乃至任何自定义脚本。docker run 参数逐项解读官方文档对上述 docker 命令的每个参数做了详尽解释整理如下参数含义docker run -it创建并交互式运行容器CtrlC 可中断--rm容器退出/停止后自动删除避免残留否则需手动docker rm--network host不启用网络隔离便于在宿主机上直接访问容器内的 TensorBoard/visdom--ipchost使用宿主机的 IPC 命名空间共享命名内存段、信号量与消息队列--name test为容器显式命名为test否则会被随机命名--mount src...将本地目录pwd映射到容器内/home/mamba/stable-baselines3容器内产生的日志因此得以保留在宿主机bash -c ...在镜像内执行命令此处即运行pytest tests/新旧 nvidia-docker 参数差异源码佐证细心的读者会发现官方文档中的 GPU 命令仍使用旧式--runtimenvidia而仓库自带的 scripts/run_docker_gpu.sh 已升级为新式参数NVIDIA_ARG--gpus all docker run -it ${NVIDIA_ARG} --rm --network host --ipchost ...--gpus all是较新版本 NVIDIA Container Toolkit 推荐的标准写法两者功能等价。在新版本 Docker NVIDIA Container Toolkit 环境下优先使用--gpus all若遇到--gpus不可用再回退到--runtimenvidia。常见安装问题排查Atari 环境报 DLL / 模块缺失错误在 Windows 上创建 Atari 环境时可能会出现与缺失 DLL 文件和模块相关的模糊报错。官方文档明确指出这是atari-py包ale-py的前身的已知问题与 SB3 本身无关。解决办法是升级到新版ale-py0.9.0即[extra]组中包含的版本或参考 atari-py 项目的 issue 讨论调整 Python 与 DLL 环境。无 X server 机器上的 OpenCV 报错如果你在没有 X server 的机器例如纯 Docker 容器、无头服务器上使用 OpenCV需要改用无头版本否则会报显示器初始化错误pip install opencv-python-headless这正是仓库 Dockerfile 构建镜像时的标准操作先装opencv-python再卸载并替换为opencv-python-headless。本机安装时也可以直接用pip install opencv-python-headless覆盖。代理环境下的 Docker 构建失败如前文所述通过代理上网时docker build拉取基础镜像和 wheel 包可能失败需要显式传入代理参数与--networkhost。若在容器内访问外网受限同样需要为容器运行时的网络与代理做相应配置。小结如何选择安装方式场景推荐方案日常训练使用含 TensorBoard、Ataripip install stable-baselines3[extra]只需最小核心库pip install stable-baselines3尝鲜 master 分支新特性pip install githttps://github.com/DLR-RM/stable-baselines3参与开发、跑测试、构建文档git clonepip install -e .[docs,tests,extra]用make pytest/make doc想要可复现的隔离环境docker pull stablebaselines/stable-baselines3GPU或-cpuCPU配合make docker-gpu/make docker-cpu自行构建无论选择哪条路径前置条件都一致Python 3.10PyTorch 2.8。安装完成后建议立即用from stable_baselines3 import PPO; PPO(MlpPolicy, CartPole-v1).learn(10_000)跑一个最小训练任务验证环境链路是否畅通。【免费下载链接】stable-baselines3PyTorch version of Stable Baselines, reliable implementations of reinforcement learning algorithms.项目地址: https://gitcode.com/GitHub_Trending/st/stable-baselines3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考