Contributing

Contributions are welcome. Before starting a substantial change, check the open issues and discuss the approach with the community. Questions and proposals can also be discussed on the PyBoy Discord.

For test dependencies, see Getting started; for source build requirements, see Install and build. For emulator architecture and the canonical test commands, see Development.

Pre-commit

PyBoy uses pre-commit to run formatting and linting before commits. Install it and register the Git hook once:

python3 -m pip install pre-commit
pre-commit install

Run the hooks manually on all files with:

pre-commit run --all-files

The normal commit hook checks staged files. The repository configuration uses Ruff for linting and formatting, and enables Ruff’s automatic fixes. Generated files such as opcodes.py, manager.py, and manager.pxd are excluded from the hooks.

Prepare changes for review

Keep each change focused and describe the behavior it changes. Add or update regression tests when fixing a bug or changing public behavior. Run the appropriate test suites from Development before requesting review.

For Cython-backed changes, rebuild before testing as described in Install and build. Keep docstring and Wiki examples executable when changing public APIs. For documentation changes, build the site and check generated links:

make docs
make docs_linkcheck

Pull requests

Use a separate branch for each contribution. In the pull request description, explain the problem and solution, link related issues, and list the checks you ran. Include screenshots for user-visible changes when they help reviewers. Contributions are distributed under the project’s LGPL license; do not include commercial game ROMs or other files you do not have permission to redistribute.