Screenshot published in the PyBoyAdvance project's official README. Image source: PyBoyAdvance project on GitHub.

PyBoyAdvance

GAME BOY EMULATOR

PyBoyAdvance

PyBoy Advance is an experimental Game Boy Advance emulator implemented in Python with Cython declarations to compile hot paths to C. It is distributed as an open-source Python package and provides a CLI and a programmatic Python API. The project is under active development and explicitly warns that some GBA features are not yet implemented.

Jump to download ↓Jump to setup guide ↓

Screenshot published in the PyBoyAdvance project's official README. Image source: PyBoyAdvance project on GitHub.

Game BoyPRIMARY SYSTEM

History documentedPROJECT BEGAN

Open sourcePROJECT MODEL

WHY IT MATTERS

Why this project exists

PyBoy Advance aims to provide a GBA emulator that is approachable from Python — useful for research, scripting, testing and learning — while using Cython to reach usable performance. It follows and credits earlier Python Game Boy projects as inspiration.

BEST FOR

Best use cases

Experimentation, automation, scripting and research where embedding an emulator directly in Python is convenient (bots, AI experiments, instrumentation). Not recommended as a primary compatibility-focused GBA emulator for playing commercial libraries due to its experimental status.

Gameplay from Tetris on Game Boy.

The people behind PyBoyAdvance

History & status

The project repository and its package (pyboy-advance) are publicly available. The repository README and PyPI description clearly label the software as experimental and under development, warn that some hardware features are missing, and require a separate Game Boy Advance BIOS to run. The implementation uses Cython to compile performance-sensitive code into C-extension modules to improve speed. The repo lists other well-known GBA projects and hardware documentation as references and inspiration. The source tree, packaging files and a command-line entry point are present in the repository.

What PyBoyAdvance supports

Game Boy Advance (GBA) ROMs (.gba)
Programmatic Python API for embedding the emulator
Command-line launcher (pyboy_advance) for running ROMs
Requires a separate GBA BIOS file (not included)

Download and availability

OFFICIAL DOWNLOADS

Get PyBoyAdvance

Install from PyPI with pip (package name: pyboy-advance) or download source/release assets from the project's GitHub releases.

Get PyBoyAdvance ↗

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.

PyBoyAdvance setup guide

Setup note: This guide covers installing the PyPI package or building from source, providing a GBA BIOS, running the emulator from the command line, and embedding it in Python scripts. Follow the repository README and PyPI page for the latest commands and any platform-specific prerequisites.

1) Prerequisites: Have Python 3.x installed. To get practical performance the project relies on Cython and building extension modules, so you need a working build toolchain for Python C extensions on your platform (for example: build-essential or a C compiler on Linux, Xcode/Command Line Tools on macOS, and Visual Studio Build Tools on Windows).
2) Install from PyPI (quick): Install the published package: pip install pyboy-advance. This installs the package and its entry point. After installation you will still need to supply a GBA BIOS file when launching the emulator.
3) Provide a GBA BIOS (required): PyBoy Advance requires a GBA BIOS file at runtime. The README documents support for Normatt's open-source BIOS, but does not include any BIOS. Place a valid BIOS binary on disk and note its path for the launcher or when instantiating the emulator from Python.
4) Run a ROM from the command line: Use the installed CLI entry point, supplying the BIOS path and a .gba ROM: pyboy_advance –bios /path/to/bios.bin /path/to/game_rom.gba. The README shows this example; command-line options and flags are documented in the repository.
5) Embed in Python scripts: Import the package and create an emulator instance: from pyboy_advance import PyBoyAdvance; emulator = PyBoyAdvance(rom='game_rom.gba', bios='/path/to/bios.bin'); emulator.run(). Use the Python API to control ticks and inputs as the project exposes programmatic control.
6) Building from source (when needed): Clone the GitHub repository and build the Cython extensions. The project includes pyproject.toml / setup.py and Cython declarations; run pip install -e . in the repo root (or python setup.py build_ext –inplace where appropriate) so the C extensions are compiled. Ensure your platform has the necessary C toolchain and Cython installed. Refer to the repository for exact build steps if the project updates them.
7) Performance & expectations: The project is written in Python with Cython-compiled modules to improve speed, but the README warns that some games may run poorly and some hardware features are unimplemented. For reliable play and broad compatibility, prefer mature GBA emulators; use PyBoy Advance for development, research, and experimentation where Python integration is required.

Software reminder: PyBoy Advance does not include any commercial game ROMs or an official GBA BIOS. You must provide your own legally obtained BIOS and ROM files. The project is experimental — expect incomplete hardware support and lower compatibility than mature GBA emulators.