# Pyxel: a 16-color retro game engine for Python

> Pyxel is a Python game engine built around retro console limits: 16 colors, 4 sound channels, and a Rust core that also compiles to WebAssembly. It suits small pixel-art projects and people learning game loops, not teams shipping 3D titles.

**kitao/pyxel** — A retro game engine for Python

- Repository: https://github.com/kitao/pyxel
- Stars: 18,304 · Forks: 961
- Language: Rust
- License: NOASSERTION
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/kitao-pyxel

## The constraint Pyxel imposes on purpose

Most Python game libraries hand you a canvas and let you decide everything else. Pyxel goes the other way. The README states the specification directly: only 16 colors can be displayed and only 4 sound channels can play at once, a design it describes as inspired by retro gaming consoles. Those are not defaults you tune later. They are the shape of the tool.

That matters for who picks it up. If you are building a platformer, a shoot-em-up, or a puzzle game in the visual language of the 8-bit and 16-bit era, the palette limit removes a whole category of decisions and keeps your art consistent whether you draw it yourself or generate it. If you are building anything photorealistic, particle-heavy, or dependent on smooth gradients, the same limit is the wall you hit in week one.

The engine is developed by one person, and the README says so plainly, framing GitHub stars as the thing that keeps it going. That is worth reading as a maintenance signal rather than a marketing line. The last push to the repository was on 2026-09-16, and releases v2.9.7, v2.9.8 and v2.9.9 landed between 2026-07-05 and 2026-08-12, so the project is moving, but the bus factor is one.

## How the Python layer sits on a Rust core

The repository is not a pure Python package. The primary language is Rust, and the top-level layout shows the split: a crates/ directory for the Rust side, a python/ directory for the binding layer, and a wasm/ directory plus a web/ directory for the browser build. The Makefile confirms the toolchain expectations, listing rustup, cmake and python 3.11+ as prerequisites, and defining a WASM target of wasm32-unknown-emscripten.

So the data flow runs from your Python script down into compiled code. You write the game loop in Python; the drawing, sound and input handling execute in the Rust crate. The Makefile also shows the WASM build is pinned to Emscripten 5.0.3, which the comment says is the version Pyodide uses. That pin is the reason the same project can run in a browser: the Rust core is compiled to a relocatable side module rather than only to a native binary.

For an application developer this mostly means one thing. The Python you write is not the performance-critical part, so you do not have to rewrite a tight loop in C to keep a frame budget. It also means the engine is not something you can patch in place with a text editor if a drawing primitive misbehaves; you are working against a compiled artifact.

## Installing Pyxel and running your first script

Pyxel is distributed on PyPI, and the README links to the project page there. The straightforward path is pip. If you are setting up a clean environment first, the Makefile's prerequisites note python3-venv on Linux, so a virtual environment is the expected workflow rather than an afterthought.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install pyxel
```

On Windows the Makefile documents the equivalent activation path as .venv/Scripts/activate under Git Bash. After installation you should be able to import the module and start the runtime from a Python file. The README points to a User Guide and a set of User Examples at kitao.github.io rather than embedding a first-program walkthrough, so the canonical starting code lives there, not in the repository README.

The engine also ships an editor. The README links to an image and tilemap editor and a sound and music editor, both runnable in the browser. Those are where the 16-color palette and the 4-channel limit become concrete: you are not editing a PNG in another tool and importing it, you are drawing inside the engine's own constraints. If you want to see the target output before writing a line of code, the pages linked from the README run example games and apps directly in the browser.

## Where Pyxel is the wrong choice

The palette and channel limits are the headline, but the sharper limitation is the build story. The Makefile lists a real toolchain: git, make, cmake, rustup, python 3.11+, node.js, and on Linux specifically clang, libclang-dev and libsdl2-dev 2.32.10. That list is for building Pyxel from source, not for using it, and the distinction matters. If a prebuilt wheel exists for your platform, pip install is enough. If it does not, you are suddenly maintaining a Rust and SDL2 build environment to make a Python game.

There is a second, quieter failure mode. The README does not document rollback, and it does not document what happens when an install fails. For a project at version 2.9.9 with releases roughly monthly, that is a gap you should test on your own machine before you plan a course or a workshop around it.

And the obvious one: if your game needs 3D, shaders, or a large third-party asset pipeline, Pyxel is not a constrained version of the right tool, it is the wrong tool. The narrow specification is the product.

## Pyxel against fantasy consoles and general Python game libraries

The comparison people reach for is PICO-8 or TIC-80, both of which appear in the repository's topic tags. The difference in approach is the language boundary. Those are self-contained fantasy consoles with their own Lua or scripting environment and their own distribution model. Pyxel is a Python library first: your code is ordinary Python, you can import the standard library, and you can install it with pip alongside the rest of your environment. You give up the sealed-console experience and gain the Python ecosystem.

Against a general-purpose Python game library, the trade runs the other way. A general library gives you an unrestricted color space and as many audio channels as the mixer allows, at the cost of having to make every aesthetic decision yourself. Pyxel pre-makes those decisions so that a small game looks coherent without an art director.

One practical consequence of the Python-first design: the same Rust core compiles to WebAssembly, and the README links to examples and tools that run as HTML pages. That is a distribution advantage a native-only engine does not have, and it comes from the architecture rather than from a separate port.

## Conclusion

Adopt Pyxel if you want a small, opinionated engine for pixel-art games and you are comfortable with a 16-color palette and 4 sound channels as hard limits. Do not adopt it if you need 3D, shaders, or a large asset pipeline; the specifications are deliberately narrow. Before committing, verify two things yourself: that pip install pyxel resolves a wheel for your platform, and that the editor and pyxel run commands work on your machine, since the README does not document rollback or a troubleshooting path for install failures.

## FAQ

### How do I install Pyxel?

Install it from PyPI with pip, ideally inside a virtual environment created with python3 -m venv. Building from source instead requires the toolchain listed in the Makefile: rustup, cmake, python 3.11+, and on Linux clang, libclang-dev and libsdl2-dev 2.32.10.

### How do I use Pyxel?

You write your game in Python and the drawing, sound and input handling run in the compiled Rust core. The README points to a User Guide and a set of User Examples for the actual starting code, and the project ships an image and tilemap editor plus a sound and music editor.

### What is Pyxel Edit?

Pyxel Edit is not this project. The repository here is Pyxel, a retro game engine for Python by kitao, distributed on PyPI and licensed under the MIT License. Its editor is the image, tilemap, sound and music editor linked from the README.

## Sources

- [Issues](https://github.com/kitao/pyxel/issues)
- [kitao/pyxel on GitHub](https://github.com/kitao/pyxel)
- [README](https://github.com/kitao/pyxel/blob/main/README.md)
- [Releases](https://github.com/kitao/pyxel/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kitao-pyxel