Installation

Starting the Emulator

It should be noted that the emulator is still under development. Even though games might work flawlessly now, be warned that saved games may be lost without any notice.

We have moved away from PyPy, as we can now get better performance with CPython + Cython! You will have to compile PyBoy before using it, but it should be easy to do. PyBoy is still compatible with PyPy, if you prefer the JIT compiler.

The code has a few dependencies, but it should be fairly easy to get it up and running. The code is primarily developed on macOS, but also has been tested with Arch Linux (and usually Ubuntu 18.04). Windows 10 Cython support is underway (pending testing & merge) but might not be 100% stable yet.

The following instructions will install the basic setup. To access screen recording and the experimental Windows (renderers), you'll need to follow the experimental features.

We assume that you have downloaded the repository already.

Note: If you have any problems, please feel free to let us know or ask for help on the Discord channel! We try our best to keep the instructions up-to-date.

macOS

The easiest way to get started is to first install brew.

When brew is installed, the dependencies can be installed with the following commands in the terminal. Assuming that you have cloned the git repo and navigated to the root-dir:

brew update
brew install python3 sdl2

python3 -m pip install cython pysdl2 numpy Pillow
python3 setup.py build_ext --inplace

You can also install PyBoy as a module on your system, so you can include it in other projects using:

python3 setup.py install build_ext

Additional note: if you want to use the screen recorder in PyPy, you'll need to do brew install libjpeg libtiff as PyPy's version of Pillow links to those libraries externally.

Ubuntu/Linux

Ubuntu's system version of Python is Python 2.7, so you can install the requirements for Python 3 without messing anything up. If you want to make a virtual environment, you will also need to install the python3-venv package.

sudo apt update
sudo apt install python3 python3-pip python3-dev libsdl2-dev build-essential

python3 -m pip install cython pysdl2 numpy Pillow
python3 setup.py build_ext --inplace

You can also install PyBoy as a module on your system, so you can include it in other projects using:

python3 setup.py install build_ext

Raspberry Pi/Raspbian

The instructions for Raspbian are almost the same as the Ubuntu/Linux instructions above. The only difference, is the need to build SDL2 from source, and modify the CFLAGS accordingly.

The instructions has been tested on a Raspberry Pi 3 model B+, running a default configuration of Raspbian Stretch Lite.

To download, build and install the newest version of SDL2 (2.0.9 at the time of writing), run the following commands:

wget https://www.libsdl.org/release/SDL2-2.0.9.tar.gz
tar zxvf SDL2-2.0.9.tar.gz
cd SDL2-2.0.9 && mkdir build && cd build

../configure --disable-pulseaudio --disable-esd --disable-video-mir --disable-video-wayland --disable-video-x11 --disable-video-opengl
make -j 4
sudo make install

If everything went well, we are ready to build PyBoy. The Makefile doesn't currently support the SDL version we just build, but we can compile PyBoy with the following:

sudo apt update
sudo apt install python3 python3-pip python3-dev build-essential

python3 -m pip install cython pysdl2 numpy Pillow
export CFLAGS=$(sdl2-config --cflags —libs)
python3 setup.py build_ext --inplace -I$(python3 -c 'import numpy; print(numpy.get_include())')

To start PyBoy, simply start the pyboy module:

python3 -m pyboy

Windows with Cython using Visual Studio Build Tools

This is a new method and these instructions are still under construction and have not been tested.

The changes needed for this method have not been merged yet, but can be found at https://github.com/krs013/PyBoy/tree/windows-native-workingcopy.

If you don't have Visual Studio installed, you will need at least to install the Visual Studio Build Tools (and maybe Windows 10 SDK?). More details to come.
Download the SDL2 development libraries at https://www.libsdl.org/release/SDL2-devel-2.0.10-VC.zip and extract all the files. There is no canonical place for them in Windows 10 but you will need the location for the next step.
Set an environment variable PYSDL2_DLL_PATH with the path to the folder containing the x86 version of SDL2.dll. This can either be done in the developer command prompt with set PYSDL2_DLL_PATH=C:\path\to\SDL2-2.0.10\lib\x86 or in Window's System Properties.
If you haven't yet, install Python 3, and optionally make a virtual environment. Then install the build requirements with python3 -m pip install cython pysdl2 numpy Pillow .
cd into the Source directory and run python3 setup.py build_ext --inplace to compile the Cython extensions.
If you want, run python3 setup.py install build_ext to copy the module into your Python installation's site-packages. (Not tested yet).

Windows with Cython on MSYS2 and mingw-w64

Install msys2-x86_64 from https://www.msys2.org, and run the MSYS2 terminal.
Update the environment by running pacman -Syu, confirming, and closing the window when prompted.
Open an MSYS2 MinGW 64-bit terminal and install the needed packages using the following command:

pacman -S make mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2 mingw-w64-x86_64-python3-pip mingw-w64-x86_64-python3-numpy mingw-w64-x86_64-python3-pillow

You may also install git by adding it to this command or separately running pacman -S git. Currently, git is required by the Makefile for make clean so for now this is a requirement.

Note: MSYS2 creates a fake home folder at C:\msys64\home\USERNAME and will open new terminals in that directory. If you wish to navigate to your Windows filesystem, it can be found in the terminal as /c/, so /c/Users/USERNAME/ is your Windows home folder. You can also just do everything in the MSYS2 home folder.

Also note: If you wish to use a virtual environment, be sure to use the --system-site-packages flag when creating the virtual environment, e.g.: python -m venv --system-site-packages pyboy-venv. Activate the environment with source pyboy-venv/bin/activate. Also, pip will encourage you to update pip, which you can do with pip install -U pip, but this may report an error. The error can be ignored and the upgrade does succeed, but the old version of pip is left in pyboy-venv/lib/python3.7/site-packages/ as two files renamed to ~ip and ~ip-19.0.3.dist-info, which can be deleted to prevent pip from warning you whenever it tries to parse them.

If you haven't already, clone the repository:

git clone https://github.com/Baekalfen/PyBoy

Enter the PyBoy/Source directory and install the Python dependencies:

python3 -m pip install cython pysdl2 numpy Pillow

Build PyBoy with:

python3 setup.py build_ext --inplace

And optionally install it to your global (or virtual environment's) site-packages with:

python3 setup.py install build_ext

Starting PyBoy

Now, find your ROM dumps, which you of course dumped yourself with PyBoyCartridge.

Then run python3 -m pyboy path/to/rom.gb from the root directory of the PyBoy Git repo. If you chose to install PyBoy on your system, you can do pyboy path/to/rom.gb from any directory.

For more advanced use, you can use python3 -m pyboy -w [Window] [ROM path]. For example: python3 -m pyboy -w SDL2 ROMs/game.rom. See more in the section experimental features.

The Game Boy controls are as follows:

Keyboard key	GameBoy equivalant
Up	Up
Down	Down
Left	Left
Right	Right
A	A
S	B
Return	Start
Backspace	Select

The other controls for the emulator:

Keyboard key	Emulator function
Escape	Quit
D	Debug
Space	Unlimited FPS
Z	Save state
X	Load state
I	Toggle screen recording
,	Rewind backwards
.	Rewind forward

Provide feedback

Saved searches

Use saved searches to filter your results more quickly