PyBoy - Game Boy Emulator in Python

2.7.0 verified Fri May 01 auth: no python

PyBoy is a Game Boy and Game Boy Color emulator written in Python, version 2.7.0. It supports full emulation including CPU, memory, graphics, and sound, with a Python API for scripting and AI research. Release cadence: irregular, ~1-2 major versions per year.

pip install pyboy

Common errors

error AttributeError: module 'pyboy' has no attribute 'PyBoy' ↓

cause Incorrect import pattern. `import pyboy` does not expose the `PyBoy` class at top level.

fix

Use from pyboy import PyBoy.

error FileNotFoundError: [Errno 2] No such file or directory: 'rom.gb' ↓

cause Missing ROM file or incorrect path.

fix

Provide a valid path to a .gb or .gbc ROM file. For testing without a ROM, you can use pyboy = PyBoy(None, window='null') but note that may cause other issues.

error ValueError: Invalid window type: 'SDL2' ↓

cause In version 2.0.0 and later, the window parameter no longer accepts 'SDL2' or 'OpenGL'.

fix

Use window='display' for a visible window, or window='null' for headless.

Warnings

breaking In version 2.0.0, the entire API was overhauled. `PyBoy` object is no longer a context manager; window_type parameter changed from 'SDL2' to 'display' or 'null'. ↓

fix Use `PyBoy(rom, window='null')` instead of `PyBoy(rom, window='SDL2')`. Do not use `with PyBoy(...):`.

gotcha PyBoy does not run on macOS with the default SDL2 display window due to missing SDL2 libraries. Use `window='null'` for headless or install SDL2 via Homebrew. ↓

fix Install SDL2 via `brew install sdl2` or use `window='null'`.

deprecated The `PyBoyWindow` class is deprecated and removed in 2.0.0; window type is now an enum parameter. ↓

fix Use `window='display'` or `window='null'` instead.

Imports

PyBoy
wrong
```
import pyboy
```
correct
```
from pyboy import PyBoy
```
direct import of module does not expose PyBoy class
PyBoyWindow
wrong
```
from pyboy import PyBoyWindow
```
correct
```
from pyboy import PyBoy
```
PyBoyWindow was removed in 2.0.0, use PyBoy directly with window_type parameter

Quickstart

Initialize PyBoy with null window (headless) and run 100 frames.

from pyboy import PyBoy

# Replace with path to a ROM file or None for no ROM
rom_path = 'rom.gb'
pyboy = PyBoy(rom_path, window='null')

# Run 100 frames (approx 1.6 seconds)
for _ in range(100):
    pyboy.tick()

pyboy.stop()