A fork of gym-retro with additional games, emulators and supported platforms
A fork of gym-retro with additional games, emulators and supported platforms
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.
| 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.
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.
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:
'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 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 |
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:
For any issues, suggestions, or discussions related to Stable-Retro, please use GitHub Issues or the Farama Foundation's Discord.
Platforms:
Python:
CPU with SSE3 or better
@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}},
}
List of papers mentioning stable-retro. If you want your paper to be added here please open a github issue.
No open issues yet, or sync has not completed.