pyboy

library2.7.0pypypi✓ verified 87d ago

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.

ai-ml

pip install pyboy

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PYBOY

pyboy

ai-mlpythonv2.7.0

Install

4.9s avg

Import

643ms

Disk

114MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.7.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 4.6s

py 3.11

✓ —

✓ 4.8s

py 3.12

✓ —

✓ 5s

py 3.13

✓ —

✓ 5.4s

py 3.9

✕ build_error

114MB installed

● package 114MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PyBoy

✓ from pyboy import PyBoy

✗ import pyboy

direct import of module does not expose PyBoy class

PyBoyWindow

✓ from pyboy import PyBoy

✗ from pyboy import PyBoyWindow

PyBoyWindow was removed in 2.0.0, use PyBoy directly with window_type parameter

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()

pyboy --version

Debug

Known issues

breakingIn 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(...):`.

affects: >=2.0.0

gotchaPyBoy 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'`.

affects: all

deprecatedThe `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.

affects: <2.0.0

Errors

Common errors & fixes

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

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

fix

Use `from pyboy import PyBoy`.

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

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.

ValueError: Invalid window type: 'SDL2'

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.

Upgrade

Version history

2.7.0latest on PyPI · released Jan 24, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Baekalfen/PyBoy ↗

packagehttps://pypi.org/project/pyboy/ ↗

docshttps://docs.pyboy.dk/index.html ↗