pygodide turns Pygame projects into browser apps using Pyodide with one command, no edits to your source code, and achieving 2.5x more FPS than pygbag (in certain cases).

Pronounced "pie-go-died"

_{Loading screen | FPS vs pygbag}

Quick Start

From your project's root directory, run the following commands:

Install

# Or add to your pyproject.toml and `uv sync`
pip install pygodide

Build

# Produces the web-hostable build/ directory
pygodide build .

# For an itch.io zip file
pygodide build . --zip

Serve

# Hosts the build/ directory locally
pygodide serve .

Open http://localhost:8000 in your browser.

Troubleshooting

If anything went wrong, work through the instructions page first (config, async, smoke tests, and common failures).

If you still cannot get your game running in the browser, open a "My project didn't convert" issue so we can improve pygodide for everyone. Paste build/pygodide-build.log into the form.

Examples and Live Demos

Sample projects live under test_targets/, and a few of them are uploaded to itch.io.

• 3D first-person demo
• Numpy particles demo
• Audio demo
• Arcade performance benchmark

Try one locally:

git clone https://github.com/Elan456/pygodide.git
cd pygodide
pip install pygodide

pygodide build test_targets/ball_bouncing
pygodide serve test_targets/ball_bouncing

Before every release, each target under test_targets/ is automatically verified using a headless browser to catch regressions. All features shown in the test targets are maintained as first-class features.

Contributing

git clone https://github.com/Elan456/pygodide.git
cd pygodide
uv sync --dev
uv run playwright install chromium
uv run pre-commit install --hook-type pre-commit --hook-type pre-push

The dev group includes pygodide[smoke], so Playwright is installed with uv sync --dev. You still need playwright install chromium once for browser binaries.

Run the same checks as CI:

uv run ruff format --check .
uv run ruff check .
uv run pytest

Smoke tests (from this repo)

uv run playwright install chromium   # once
uv run pygodide smoke /path/to/your/pygame/project
uv run pygodide smoke test_targets --suite

Be sure to read AGENTS.md; it is written for both human contributors and AI tools.