(install)=

# Installation

## Prerequisites

Stable-Baselines3 requires python 3.10+ and PyTorch >= 2.8

### Windows

We recommend using [miniforge](https://github.com/conda-forge/miniforge#windows) for Windows users for easier installation of Python packages and required libraries. You need an environment with Python version 3.10 or above.

For a quick start you can move straight to installing Stable-Baselines3 in the next step.

:::{note}
Trying to create Atari environments may result in vague errors related to missing DLL files and modules. This is an
issue with atari-py package. [See this discussion for more information](https://github.com/openai/atari-py/issues/65).
:::

### Stable Release

To install Stable Baselines3 with pip, execute:

```bash
pip install 'stable-baselines3[extra]'
```

:::{note}
Some shells such as Zsh require quotation marks around brackets, i.e. `pip install 'stable-baselines3[extra]'` [More information](https://stackoverflow.com/a/30539963).
:::

This includes optional dependencies like Tensorboard, OpenCV or `ale-py` to train on Atari games. If you do not need those, you can use:

```bash
pip install stable-baselines3
```

:::{note}
If you need to work with OpenCV on a machine without a X-server (for instance inside a docker image),
you will need to install `opencv-python-headless`, see [issue #298](https://github.com/DLR-RM/stable-baselines3/issues/298).
:::

## Bleeding-edge version

```bash
pip install git+https://github.com/DLR-RM/stable-baselines3
```

with extras:

```bash
pip install "stable_baselines3[extra,tests,docs] @ git+https://github.com/DLR-RM/stable-baselines3"
```

## Development version

To contribute to Stable-Baselines3, with support for running tests and building the documentation.

```bash
git clone https://github.com/DLR-RM/stable-baselines3 && cd stable-baselines3
pip install -e '.[docs,tests,extra]'
```

## Using Docker Images

If you are looking for docker images with stable-baselines already installed in it,
we recommend using images from [RL Baselines3 Zoo](https://github.com/DLR-RM/rl-baselines3-zoo).

Otherwise, the following images contained all the dependencies for stable-baselines3 but not the stable-baselines3 package itself.
They are made for development.

### Use Built Images

GPU image (requires [nvidia-docker]):

```bash
docker pull stablebaselines/stable-baselines3
```

CPU only:

```bash
docker pull stablebaselines/stable-baselines3-cpu
```

### Build the Docker Images

Build GPU image (with nvidia-docker):

```bash
make docker-gpu
```

Build CPU image:

```bash
make docker-cpu
```

Note: if you are using a proxy, you need to pass extra params during
build and do some [tweaks]:

```bash
--network=host --build-arg HTTPS_PROXY=https://your.proxy.fr:8080/ --build-arg https_proxy=https://your.proxy.fr:8080/
```

### Run the images (CPU/GPU)

Run the nvidia-docker GPU image

```bash
docker run -it --runtime=nvidia --rm --network host --ipc=host --name test --mount src="$(pwd)",target=/home/mamba/stable-baselines3,type=bind stablebaselines/stable-baselines3 bash -c 'cd /home/mamba/stable-baselines3/ && pytest tests/'
```

Or, with the shell file:

```bash
./scripts/run_docker_gpu.sh pytest tests/
```

Run the docker CPU image

```bash
docker run -it --rm --network host --ipc=host --name test --mount src="$(pwd)",target=/home/mamba/stable-baselines3,type=bind stablebaselines/stable-baselines3-cpu bash -c 'cd /home/mamba/stable-baselines3/ && pytest tests/'
```

Or, with the shell file:

```bash
./scripts/run_docker_cpu.sh pytest tests/
```

Explanation of the docker command:

- `docker run -it` create an instance of an image (=container), and
  run it interactively (so ctrl+c will work)
- `--rm` option means to remove the container once it exits/stops
  (otherwise, you will have to use `docker rm`)
- `--network host` don't use network isolation, this allows to use
  tensorboard/visdom on host machine
- `--ipc=host` Use the host system’s IPC namespace. IPC (POSIX/SysV IPC) namespace provides
  separation of named shared memory segments, semaphores and message
  queues.
- `--name test` give explicitly the name `test` to the container,
  otherwise it will be assigned a random name
- `--mount src=...` give access of the local directory (`pwd`
  command) to the container (it will be map to `/home/mamba/stable-baselines`), so
  all the logs created in the container in this folder will be kept
- `bash -c '...'` Run command inside the docker image, here run the tests
  (`pytest tests/`)

[nvidia-docker]: https://github.com/NVIDIA/nvidia-docker
[tweaks]: https://stackoverflow.com/questions/23111631/cannot-download-docker-images-behind-a-proxy