Screenshot of the EmuHawk emulator frontend taken on a Linux (NixOS) PC. The Game Boy Color homebrew game µCity is loaded, using the Gambatte emulation core. Image by YoshiRulz, via Wikimedia Commons (CC BY-SA 4.0).

PyBoy

GAME BOY COLOR EMULATOR

PyBoy

PyBoy is an open-source Game Boy and Game Boy Color emulator implemented in Python with an API designed for scripting, AI, and research.

Jump to download ↓Jump to setup guide ↓

game boy colorPRIMARY SYSTEM

History documentedPROJECT BEGAN

Open sourcePROJECT MODEL

WHY IT MATTERS

Why PyBoy exists

PyBoy was created as a pure-Python Game Boy implementation with a first-class scripting/API surface so researchers, hobbyists, and AI authors can run, inspect and control Game Boy games from Python programs.

BEST FOR

What PyBoy is best for

Scripting, automated playtesting, reinforcement-learning/AI experiments, instrumentation and teaching. It is convenient to embed in Python workflows and to control programmatically; it is not intended to compete with high-performance C/C++ emulators when absolute speed or cycle-accurate commercial-game compatibility is required.

Gameplay from Wario Land 3 on Game Boy Color.

The people behind PyBoy

History and status

PyBoy is maintained on GitHub (Baekalfen/PyBoy) and has an active documentation site and periodic releases. Over time the project gained Game Boy Color support and an API for programmatic control, and it is used in RL/AI projects and academic work. Prebuilt packages are published on PyPI and release assets appear on the project's GitHub releases page. The project is actively developed as an open-source Python library; for the current release state consult the project's releases page and documentation (sources listed below).

What PyBoy supports

Nintendo Game Boy (DMG)
Nintendo Game Boy Color (CGB)
Host platforms: Linux, macOS, Windows (via Python & dependencies)
Python embedding and scripting (PyBoy Python API)

Download and availability

OFFICIAL DOWNLOADS

Get PyBoy

You can install PyBoy from PyPI (pip install pyboy) or download release assets/source from the project's GitHub releases. For development or the latest changes clone the official repository and follow the repository's installation instructions.

Get PyBoy ↗

DOCUMENTATION

Official documentation

Read the official configuration, compatibility, and troubleshooting material before changing advanced options.

Read official documentation ↗

Broken or missing download? Emulator projects move and official links sometimes change. Please contact Retro Replay so the source can be verified and updated.

PyBoy setup guide

Setup note: Practical setup notes — verified from the project documentation and installation wiki. These steps assume familiarity with Python virtual environments and installing system packages when required (SDL2 and related libraries for the graphical backend).

1) Choose install method: Option A — PyPI: pip install pyboy (convenient for most users). Option B — From source: git clone the GitHub repo and install with pip (pip install -e .) if you want the latest code or to contribute.
2) Prepare a Python environment: Create and activate a virtual environment (python -m venv venv; source venv/bin/activate on Unix or venv\Scripts\activate on Windows). Then install pyboy in that environment so dependencies don’t interfere with system Python packages.
3) Install system dependencies for the window/audio backend: PyBoy's default window backend is SDL2 (the project accepts window='SDL2'). On Linux/macOS/Windows install SDL2 and any development headers required by your platform package manager before installing from source. If installing from PyPI, many users still need the platform's SDL2 runtime for the graphical window to work. See the project's Installation wiki for platform-specific hints.
4) Run an ROM: After installation you can run a ROM from the command line (python3 -m pyboy path/to/ROM.gb). You may also load ROMs inside Python by importing and instantiating the PyBoy object from the library and using the API for step-based control and screen access.
5) Optional: Game Boy Color features and options: PyBoy supports Game Boy Color features. The emulator exposes options (such as cgb, bootrom, ram/rtc files and color palettes) through its API and command-line interface; consult the API docs for the exact parameters to enable CGB-specific behavior or to supply optional BIOS/boot ROM files. The project does not include any commercial game ROMs or proprietary BIOS files.
6) Automation, bots and RL integration: PyBoy is designed to be controlled from Python code: retrieve the framebuffer, read/write registers or memory, inject input, and step the emulator programmatically. Use the documented PyBoy API for building AI agents or automated test harnesses; the documentation contains API references and plugin interfaces.
7) Troubleshooting and performance: Because PyBoy is Python-based, real-time performance depends on host CPU and Python interpreter. If you need more speed, consider running on PyPy/Cython if supported, or use smaller display scales and disable unnecessary logging. Check the project's wiki and issue tracker for platform-specific tips and known issues.

Software reminder: PyBoy does not include game ROMs, commercial firmware, or BIOS files. You must provide your own legally obtained ROMs and any proprietary BIOS/boot ROMs if you choose to use them.