This page covers setting up the Python environment for developing and testing PyBoy. For platform-specific installation, see Install and build for the per-platform install and source-build instructions.
You need Python 3. Use a virtual environment to keep project dependencies separate from system Python. The compiler and RGBDS requirements for source builds are listed in Install and build.
Clone the repository, create and activate a virtual environment using the instructions for your platform, then install the development and test dependencies from the repository root:
python -m pip install -r requirements_tests.txt
This file includes the base requirements from requirements.txt as well as
pytest and the project’s test dependencies. To build the Sphinx documentation,
also install its optional dependencies:
python -m pip install ".[docs]"
Follow the source-build instructions for your platform in Install and build to compile the Cython extensions and ROM artifacts.
Point PyBoy at a ROM file you are entitled to use. For example:
python -m pyboy path/to/rom.gb
If PyBoy is installed as a package, you can run it from any directory:
pyboy path/to/rom.gb
Use python -m pyboy --help to see the available options. For example,
python -m pyboy -w SDL2 path/to/rom.gb selects the SDL2 window. See
Plugins and game wrappers
for more options.
| Keyboard key | Game Boy control |
|---|---|
| Up, Down, Left, Right | Directional pad |
| A | A |
| S | B |
| Return | Start |
| Backspace | Select |
| Keyboard key | Emulator function |
|---|---|
| Escape | Quit |
| D | Debug |
| Space | Unlimited FPS |
| Z | Save state |
| X | Load state |
| I | Toggle screen recording |
| , | Rewind backwards |
| . | Rewind forwards |
To enable rewind, see Plugins and game wrappers.