Farama-Foundation/Stable-Retro

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

System	Linux	Windows	Apple
Atari 2600	✓	✓	✓
NES	✓	✓	✓
SNES	✓	✓	✓
Nintendo 64	✓†	✓†	—
Nintendo DS	✓	✓	✓
Gameboy/Color	✓	✓	✓*
Gameboy Advance	✓	✓	✓
Sega Genesis	✓	✓	✓
Sega Master System	✓	✓	✓
Sega CD	✓	✓	✓
Sega 32X	✓	✓	✓
Sega Saturn	✓	✓	✓
Sega Dreamcast	✓‡	—	—
PC Engine	✓	✓	✓
Arcade Machines	✓	✓	—

* 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:

Category	Games
Platformers	Super Mario World, Sonic The Hedgehog 2, Mega Man 2, Castlevania IV
Fighters	Mortal Kombat Trilogy, Street Fighter II, Fatal Fury, King of Fighters '98
Sports	NHL94, NBA Jam, Baseball Stars
Puzzle	Tetris, Columns
Shmups	1943, Thunder Force IV, Gradius III, R-Type
BeatEmUps	Streets Of Rage, Double Dragon, TMNT 2: The Arcade Game, Golden Axe, Final Fight
Racing	Super Hang On, F-Zero, OutRun
RPGs (experimental)	Pokemon Red, Legend Of Zelda, Final Fantasy, Dragon Warrior

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.

Topic	Description
Windows WSL2 Setup	Step-by-step guide for setting up stable-retro on Windows 11 with WSL2 and Ubuntu 22.04
Game Integration Tool	Playlist covering how to use the integration tool to add new games
RetroArch + ML Models	Running a custom RetroArch build that supports overriding player input with trained models

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
• StatePlay: State-Aware Game World Models for Mechanics-Consistent Generation
• FootsiesGym: A Fighting Game Benchmark for TwoPlayer Zero-Sum Imperfect-Information Games