Pyxel

2.9.5 verified Sat May 09 auth: no python

A retro game engine for Python, designed for creating pixel-art games. Latest version: 2.9.5. Release cadence: irregular, major updates every few months.

pip install pyxel

Common errors

error ModuleNotFoundError: No module named 'pyxel' ↓

cause Pyxel not installed or Python version <3.10.

fix

Install with pip install pyxel and ensure Python >=3.10.

error pyxel.init() takes 2 positional arguments but 3 were given ↓

cause Old code passing caption as third argument; modern pyxel.init() only takes width, height.

fix

Remove the caption argument: pyxel.init(160, 120) instead of pyxel.init(160, 120, "My Game").

error AttributeError: module 'pyxel' has no attribute 'App' ↓

cause Old code using `pyxel.App` which was removed in 2.0.

fix

Use pyxel.run(update, draw) inside a class or functions. See quickstart.

Warnings

breaking Pyxel 2.0 introduced many breaking changes: API redesigned, removed old classes like `pyxel.App`, `pyxel.Image`, etc. Functions now use lower_case instead of camelCase. ↓

fix Rewrite to use new API: `pyxel.init()` instead of `pyxel.init(width, height, caption)`, `pyxel.run()` instead of `pyxel.App().run()`, `pyxel.btnp()` instead of `pyxel.btn()` for press detection.

gotcha On macOS, Pyxel may fail to launch if the terminal doesn't have accessibility permissions. The window may appear but is unresponsive. ↓

fix Grant Accessibility permission to the terminal (System Preferences → Security & Privacy → Privacy → Accessibility → add your terminal app).

breaking Pyxel 2.2 changed the default palette from 16 colors to the PICO-8 palette. Existing projects may look different. ↓

fix Use `pyxel.colors.from_list(pyxel.COLORS_16)` to restore old palette, or adjust colors.

Imports

pyxel
wrong
```
from pyxel import *
```
correct
```
import pyxel
```
Wildcard imports discouraged; import pyxel then use pyxel.init(), etc.

Quickstart

Minimal Pyxel app with a window, update loop, and quit on Q.

import pyxel

pyxel.init(160, 120)

class App:
    def __init__(self):
        pyxel.run(self.update, self.draw)

    def update(self):
        if pyxel.btnp(pyxel.KEY_Q):
            pyxel.quit()

    def draw(self):
        pyxel.cls(0)
        pyxel.text(55, 41, "Hello, Pyxel!", 7)

App()