Skip to content

pygodide turns Pygame projects into browser apps using Pyodide. It bundles your code and assets, installs Python dependencies in the browser, and generates the HTML and JavaScript needed to run your game on the web.

Performance

On the perf_bench workload, a reference run reported 433 FPS in pygodide vs 180 FPS in pygbag (headed Chromium; local desktop 950 FPS).

Full benchmark details ยท Reproduce locally

Install

pip install pygodide

For pygodide smoke (headless browser check), install the smoke extra and Chromium once:

pip install 'pygodide[smoke]'
playwright install chromium

Then run pygodide smoke . from your game project. See smoke testing for the full flow.

Quick start

From your project root:

pygodide build .
pygodide serve .

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

Pygodide looks for main() in main.py, reads dependencies from requirements.txt or pyproject.toml, and auto-converts simple game loops for the browser. That covers most small projects without extra setup.

When it works, your game is a normal web page: easy to host, link, and share. See Publishing to itch.io for a zip upload, or Publishing to GitHub Pages to serve build/ from a repository.

Need more help?

See the Instructions guide for:

  • troubleshooting when the quick start does not work
  • setting a custom entry point or dependencies
  • making your game async-compatible
  • running pygodide smoke to check a build before debugging in the browser
  • publishing to itch.io or GitHub Pages

For the full flag list generated from the CLI source, see the CLI reference.

Common commands

Command What it does
pygodide build . Bundle into build/
pygodide serve . Serve the built app locally (default port 8000)
pygodide serve . --port 3000 Serve on a different port
pygodide smoke . Build and test in a headless browser
pygodide build . --app game:start Use a different entry function
pygodide build . --dep numpy Add an extra dependency for this build
pygodide build . --canvas-fit Scale to max viewport size keeping game aspect
pygodide build . --canvas-width 960 --canvas-height 540 --canvas-fit Fit using an explicit aspect (when discovery fails)
pygodide build . --canvas-fill Stretch to fill the full viewport (may change aspect)
pygodide build . --canvas-width 1280 --canvas-height 720 Fixed HTML canvas size (stretches Pygame output)
pygodide build . --zip Build and create an itch.io-ready ZIP

Build output is logged to build/pygodide-build.log. Smoke tests also write build/pygodide-smoke.log.

Examples

Working sample projects live in the test_targets directory on GitHub, including:

Live demos

A few demos built with pygodide are hosted on itch.io: