Linux Installation

June 14, 2026 ยท View on GitHub

This guide covers installing Stable Retro on Linux distributions.

Requirements

  • Python 3.10 to 3.14
  • Linux (manylinux1 compatible)
  • CPU with SSE3 or better
  • Ubuntu 22.04 is recommended

Standard Installation

For most users, the simplest installation method is via pip:

pip3 install stable-retro

If the above doesn't work for your distribution:

pip3 install git+https://github.com/Farama-Foundation/stable-retro.git

Development Installation

If you plan to integrate new ROMs, states or emulator cores, or plan to edit an existing environment:

git clone https://github.com/Farama-Foundation/stable-retro.git
cd stable-retro
pip3 install -e .

Ubuntu/Debian Installation

System Dependencies

Install the required system packages:

sudo apt-get update
sudo apt-get install python3 python3-pip git zlib1g-dev libopenmpi-dev ffmpeg

With Stable Baselines 3

For reinforcement learning with Stable Baselines 3:

pip3 install git+https://github.com/Farama-Foundation/stable-retro.git
pip3 install stable_baselines3[extra]

Building from Source

For development or to access the latest features:

Install Build Dependencies

sudo apt-get update
sudo apt-get install build-essential cmake pkg-config libzip-dev liblua5.3-dev \
    qtbase5-dev capnproto libcapnp-dev

Nintendo 64 Core (Parallel N64)

The N64 core requires OpenGL headers to build. Install them with:

sudo apt-get install libgl1-mesa-dev

On Fedora/RHEL:

sudo dnf install mesa-libGL-devel

On Arch Linux:

sudo pacman -S mesa

If OpenGL headers are not found, the N64 core will be skipped during build. You can also explicitly disable it with -DBUILD_N64=OFF.

Dreamcast Core (Flycast)

The Flycast core requires hardware rendering support. It uses EGL or GLX for headless OpenGL rendering.

Additional dependencies:

sudo apt-get install libegl1-mesa-dev libgles2-mesa-dev

Required environment variable for headless rendering:

When running on a headless server (no display), set:

export DISPLAY=:0

Or use a virtual framebuffer:

Xvfb :99 -screen 0 640x480x24 &
export DISPLAY=:99

Build with hardware rendering enabled:

pip install -e . -DENABLE_HW_RENDER=ON

Clone and Build

git clone https://github.com/Farama-Foundation/stable-retro.git
cd stable-retro
pip3 install -e .

Build Integration UI (Optional)

To build the game integration UI:

cmake . -DBUILD_UI=ON -UPYLIB_DIRECTORY
make -j$(nproc)
./gym-retro-integration

Windows WSL2

Stable Retro works well on Windows 11 WSL2 with Ubuntu.

See the video tutorial: Windows WSL2 + Ubuntu 22.04 setup guide

Verify Installation

After installation, verify it works by running:

import stable_retro
env = stable_retro.make(game='Airstriker-Genesis-v0')
print("Installation successful!")
env.close()

Troubleshooting

Common Issues

  • Import errors: Ensure you have the correct Python version (3.10-3.14)
  • Missing shared libraries: Install the required system dependencies listed above
  • Permission errors: You may need to use pip3 install --user or a virtual environment
  • 32-bit systems: Not supported due to compatibility issues with some cores

Using a virtual environment helps avoid dependency conflicts:

python3 -m venv retro-env
source retro-env/bin/activate
pip install stable-retro