CDN root used by pygbag

Github repo, and older runtimes

This software does not track usage at all, even for statistics purpose so if you like it : please do not forget to star it !

Pygbag WIKI

IMPORTANT ALL: add --template noctx.tmpl to pygbag command line when using 3D/WebGL


IMPORTANT MAC users : if you get SSL error, use the file “Install Certificates.command” in Applications/Python 3.XX

IMPORTANT Linux users: when using webusb ftdi serial emulation use sudo rmmod ftdi_sio after plugging devices.

IMPORTANT ALL: when importing complex wheels that depend on each other, always put them in order (but numpy first) in

IMPORTANT ALL: Please do not use wav/mp3 audio formats when packaging, pygbag would not work.

Before packaging, adapt your code this way if you still want wav format on desktop :

if sys.platform == "emscripten":
    snd = pygame.mixer.Sound("sound.ogg")
    snd = pygame.mixer.Sound("sound.wav") # or .WAV,.mp3,.MP3

also avoid raw format like BMP for your assets they are too big for web use. prefer PNG or JPG ___

template project

There is none actually, because pygbag is not a framework it is just a friendly web version of official CPython (nothing has been changed, just some facilities added). Most desktop code will run (and will continue to run) with only a few lines changes. This is actually true for games but for applications it can be very difficult to port, even sometimes impossible.

Try to avoid relying on CPython stdlib for web operations, gui or I/O as it is very synchronous, platform specific and will probably stay that way. As alternative using pygame or pygbag supported game engines will ensure you platform independence including access to mobile ones.

basic structure of a game should be like :

├── img
│   ├── pygc.bmp
│   ├── pygc.png
│   └── tiger.svg
└── sfx
    └── beep.ogg

then run pygbag test/ against it, and first goes to http://localhost:8000?-i (with terminal and debugging info, for older pygbag version use http://localhost:8000#debug instead) or http://localhost:8000 (fullscreen windowed when it is running ok)

usefull additions to your .gitignore



if using pygame zero : put #!pgzrun near the top of main ( 2nd line is perfect if file already has a shebang )




how to package a game


Demos on github pages :

(for testing, may not always work since they use daily/weekly devel version)

heavy cpu load not for low-end devices:

Perfect Rain

Alien Dimension

Light cpu load :



Penguins Can’t Fly !

John’s Adventure

3D Tic-Tac-Toe


Sudoku Solver

view code from above games and others on github

[view the code]

Please ! use the tag pygame-wasm for your projects hosted on Github and also add a favicon.png icon 32x32 next to your game, so it is picked up by default.

Demos on

( expected to be stable )

games on

Script demos

nb : code is read-only, prefer right-click then open in new window.

i18n bidi,complex scripts



Audio Record/Play

Html output



Python Wasm explained by core dev Christian Heimes (youtube video)

Early demos from above talk, may not fully work as intended :)

pygame tech demo PyCon DE & PyData Berlin 2022

Galaxy Attack

French : Python WebAssembly at PyCon FR 2023 Pour quoi, pour qui et comment

current status

explore current issues

PyPI stats


Thanks for supporting pygame and pygbag. Without support now, there won’t be pygame or pygbag later.

Hello from the pygame community.

Connect with Discord

Pygame community


edit this page