pyxel

pyxelpyxel run script.pypyxel watch directory script.pypyxel play app.pyxapppyxel edit [resource.pyxres]pyxel package appdir startup.py_pyxel app2exe app.pyxapppyxel app2html app.pyxapppyxel copy_examples

pyxel is the command installed with the Pyxel Python library, a retro game engine with a fixed 16-color palette, four sound channels, image banks, and tilemaps. Games are ordinary Python scripts (import pyxel, then pyxel.init and pyxel.run). The same command opens the bundled resource editor and packs a project for other machines or for the browser.With no arguments it prints the version and the command list.While a game or the editor is running: Esc quits; Alt+1 saves a screenshot to the desktop; Alt+3 saves up to 10 seconds of capture; Alt+Enter toggles fullscreen; Alt+0 toggles the performance monitor. On macOS the Alt shortcuts use Option.

run script.py

Run a Python file. A missing .py suffix is added. The script's directory is put on sys.path.

Run script.py and restart it when any file under directory changes. Stop with Ctrl+C (Cmd+C on macOS). The script must live inside directory.

Unpack and run a Pyxel application file. .pyxapp is added when the name has no suffix. A .zip path is accepted as-is.

Open the image, tilemap, sound, and music editors. Omitted name becomes my_resource.pyxres. A missing file is created. A missing .pyxres suffix is added.

Write appdir**.pyxapp** (a zip) in the current directory. startup.py must be inside appdir. Comment headers in that file (title, author, desc, site, license, version) are stored as zip metadata and printed by play. .gif, .zip, and __pycache__ are left out.

Build a windowed executable with PyInstaller. Fails if PyInstaller is not installed.

Write name.html in the current directory. The page loads Pyxel's web runtime and embeds the .pyxapp.

Replace ./pyxel_examples with the examples shipped in the package.

Needs Python 3.11 or newer. The pyxel command comes from pip install pyxel (or a distro package of that project), not from the Python standard library. Games open a graphical window; this is not a terminal game. watch errors if the script is outside the watched directory. app2exe depends on PyInstaller and writes build files in the working directory. app2html needs network access when the page is opened, because it loads the web runtime from a CDN pinned to the installed Pyxel version.

python(1), pygame(1), pip(1)

Source code · Documentation