pygbag

Package Pygame games for web browsers

TLDR

Package game for web

$ pygbag [path/to/game]

Specify output directory

$ pygbag --build [path/to/game]

Run development server

$ pygbag --dev [path/to/game]

Custom archive name

$ pygbag --archive [name] [path/to/game]

Specify custom port for dev server

$ pygbag --port [8000] [path/to/game]

Specify template

$ pygbag --template [template.html] [path/to/game]

SYNOPSIS

pygbag [--build] [--dev] [options] path

pygbag packages Pygame applications for deployment in web browsers by compiling Python code to WebAssembly using Emscripten and Pyodide. The resulting build runs directly in modern browsers without plugins, making it straightforward to share Python games and multimedia applications online.
The tool includes a built-in development server for local testing before deployment. Games must use async Python patterns with asyncio to work within the browser's event loop model. pygbag handles asset bundling, HTML template generation, and the WebAssembly compilation pipeline, producing a self-contained web application from a standard Pygame project.

PARAMETERS

--build

Build only, no server.

--dev

Development mode.

--archive NAME

Archive filename.

--template FILE

Custom HTML template.

--port PORT

Port for the development server (default: 8000).

--cdn URL

CDN base URL.

--title TITLE

Page title.

--ume_block SIZE

Set the maximum cache block size.

CAVEATS

Not all Python libraries are supported in the WebAssembly environment; C extensions must be specifically compiled for Emscripten. The main game loop must use `asyncio` with `await asyncio.sleep(0)` for browser compatibility. The entry point must be named `main.py`. Resulting builds can be large due to the Python runtime being included.

HISTORY

pygbag was created to bring Pygame games to web browsers using WebAssembly and Pyodide.