github.com/Farama-Foundation/Stable-Retro @v1.0.1

<a href="https://gymnasium.farama.org/" target = "_blank">
<img src="https://github.com/Farama-Foundation/Stable-Retro/raw/v1.0.1/docs/_static/img/stable-retro-text.png" width="500px" />

A fork of gym-retro ('lets you turn classic video games into Gymnasium environments for reinforcement learning') with additional games, emulators and supported platforms. Since gym-retro is in maintenance now, you can instead submit PRs with new games or features here in stable-retro.

• Supported emulators
• Supported games/envs

Emulated Systems

* On Apple Silicon (arm64), Gambatte (GB) is skipped by default in the CMake build.

† Built by default when BUILD_N64=ON and OpenGL headers are available. If headers are missing, the build skips the N64 core.

‡ Only available when hardware rendering is enabled (ENABLE_HW_RENDER=ON). Hardware rendering support is currently Linux-only in this project.

Supported Games

Currently over 1000 games are integrated including:

Note: If the game you want is not included but is supported by one of the systems in the list above, an integration tool is provided to help add new games.

Installation

Stable Retro supports Python 3.10 through 3.14.

pip3 install stable-retro

or if the above doesn't work for your platform:

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

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

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

For platform-specific instructions including building from source, optional core dependencies, and the Integration UI: - Linux Installation - Ubuntu/Debian dependencies, N64 and Dreamcast core setup, WSL2 guide - macOS Installation - Apple Silicon build instructions, Homebrew dependencies

Example

'Nature CNN' model trained using PPO on Airstriker-Genesis env (rom already included in the repo)

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

You need to install a stable baselines 3 version that supports gymnasium

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

Start training:

cd retro/examples
python3 ppo.py --game='Airstriker-Genesis-v0'

More advanced examples: https://github.com/MatPoliquin/stable-retro-scripts

Documentation & Tutorials

Documentation is available at https://stable-retro.farama.org/ (work in progress)

See LICENSES.md for information on the licenses of the individual cores.

ROMs and BIOS files

Each game integration has files listing memory locations for in-game variables, reward functions based on those variables, episode end conditions, savestates at the beginning of levels and a file containing hashes of ROMs that work with these files.

Please note that ROMs are not included and you must obtain them yourself. Most ROM hashes are sourced from their respective No-Intro SHA-1 sums.

Run this script in the roms folder you want to import. If the checksum matches it will import them in the related game folder in stable-retro.

python3 -m retro.import .

Some platforms like Sega Saturn and Dreamcast also need to be provided a BIOS. List of BIOS names and checksums.

The following non-commercial Sega Genesis ROM is included with Stable Retro for testing purposes: - Airstriker by Electrokinesis

List of other included ROMs.

Contributing & Support

See CONTRIBUTING.md

For any issues, suggestions, or discussions related to Stable-Retro, please use GitHub Issues or the Farama Foundation's Discord.

Supported specs:

Platforms: - Windows 10, 11 (via WSL2) - macOS 10.13 (High Sierra), 10.14 (Mojave) - Linux (manylinux1). Ubuntu 24.04 is recommended

Python: - Python 3.10 through 3.14

CPU with SSE3 or better

Citation

@misc{stable-retro,
  author = {Poliquin, Mathieu},
  title = {Stable Retro, a maintained fork of OpenAI's gym-retro},
  year = {2026},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/Farama-Foundation/stable-retro}},
}

Papers

List of papers mentioning stable-retro. If you want your paper to be added here please open a github issue.

• Exploration-Driven Generative Interactive Environments
• Gymnasium: A Standardized Interface for Reinforcement Learning Environments
• IPR-1: Interactive Physical Reasoner
• SAFE-SMART: Safety Analysis and Formal Evaluation using STL Metrics for Autonomous RoboTs
• General Modular Harness for LLM Agents in Multi-Turn Gaming Environments
• ReactiveGWM: Steering NPC in Reactive Game World Models
• Dissecting Discrete Soft Actor-Critic: Limitations and Principled Alternatives