Skip to content
Game Boy emulator written in Python
Python TeX Other
Branch: master
Clone or download

Latest commit

Latest commit d7d3659 May 17, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
Projects Fixed sdl2 path May 15, 2020
README V1.0.0 Apr 19, 2020
bootrom V1.0.0 Apr 19, 2020
default_rom Add default rom (#133) May 15, 2020
docker V1.0.0 Apr 19, 2020
docs Updated docs May 15, 2020
examples Add randomization to game wrappers (#147) May 15, 2020
pyboy Fixed save states with 16-bit variables May 15, 2020
test_results Add randomization to game wrappers (#147) May 15, 2020
tests Fixed Mario testing May 15, 2020
.coveragerc WARNING: This commit restructures the source tree. Support both PyPy … Dec 23, 2019 Fixing Windows deploy May 17, 2020
.dockerignore Docker integration Jan 28, 2020
.gitignore Pull Request testing + mooneye + acid + blargg (#150) May 15, 2020
.isort.cfg Fixed identifiers and added some error handling in save/load state Sep 4, 2019
.pre-commit-config.yaml V1.0.0 Apr 19, 2020
.style.yapf V1.0.0 Apr 19, 2020
.travis.yml Fixing Windows deploy May 17, 2020 Create (#165) May 15, 2020
LICENSE.SDL2.txt V1.0.0 Apr 19, 2020
LICENSE.SDL2_PXD.txt V1.0.0 Apr 19, 2020 V1.0.0 Apr 19, 2020
Makefile V1.0.0 Apr 19, 2020
PyBoy.pdf Added report Jan 25, 2016 Update Apr 24, 2020
ci_secrets.tar.enc Travis (#115) Mar 13, 2020 Create (#165) May 15, 2020
requirements.txt Removed _dummy_declarations and require Cython version May 15, 2020 Fixing Windows deploy May 17, 2020

If you have any questions, or just want to chat, join us on Discord.

It is highly recommended to read the report to get a light introduction to Game Boy emulation. But do be aware, that the Python implementation has changed a lot. The report is relevant, eventhough you want to contribute to another emulator, or create your own.

If you've read the report and want more explicit details, have a look at the Pan Docs.

If you are looking to make a bot or AI, you can find all the external components in the PyBoy Documentation. There is also a short example on our Wiki page Scripts, AI and Bots as well as in the examples directory. If more features are needed, or if you find a bug, don't hesitate to make an issue here on GitHub, or write on our Discord channel.


The instructions are simple, if you already have a functioning Python environment on your machine.

  1. Install SDL2 through your package manager:

    • Ubuntu: sudo apt install libsdl2-dev
    • Fedora: sudo dnf install SDL2-devel
    • macOS: brew install sdl2
  2. Install PyBoy using pip install pyboy (add --user if your system asks)

Now you're ready! Either use PyBoy directly from the terminal $ pyboy file.rom or use it in your Python scripts:

from pyboy import PyBoy
pyboy = PyBoy('ROMs/')
while not pyboy.tick():

If you need more details, or if you need to compile from source, check out the detailed installation instructions. We support: macOS, Raspberry Pi (Raspbian), Linux (Ubuntu), and Windows 10.

At the Wiki page, you will also find out how to interface with PyBoy from your own project: Wiki.


Thanks to all the people, who have contributed to the project!

Original Developers

GitHub Collaborators

Student Projects

  • Rewind Time: Jacob Olsen - JacobO1
  • Link Cable: Jonas Flach-Jensen - thejomas


Any contribution is appreciated. The currently known errors are registered in the Issues tab. Feel free to take a swing at any one of them.

For the more major features, there are the following that you can give a try. They are also described in more detail in the project list:

  • Color
  • Link Cable
  • (Experimental) AI - use the botsupport or game wrappers to train a neural network
  • (Experimental) Game Wrappers - make wrappers for popular games

If you want to implement something which is not on the list, feel free to do so anyway. If you want to merge it into our repo, then just send a pull request and we will have a look at it.

You can’t perform that action at this time.