Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/VKSFY/keel/llms.txt

Use this file to discover all available pages before exploring further.

Keel is distributed on PyPI under the name keelpy. The import name inside your code is keel. This distinction — PyPI name vs. import name — is the single most common source of confusion for new users, so keep it in mind as you work through this page. The rest of the install is a standard pip one-liner.

​
Requirements

Before installing, make sure your environment meets both requirements:
  • Python 3.10 or newer — Keel supports Python 3.10, 3.11, and 3.12. Pre-built wheels are available on PyPI for all three versions on Windows, macOS, and Linux.
  • OpenGL 3.3 Core — a GPU and driver that support OpenGL 3.3 Core Profile. This covers any discrete GPU from the last decade and most integrated graphics from Intel (Haswell, 2013+), AMD, and Apple Silicon via MoltenVK. Headless CI typically needs a software renderer such as Mesa’s llvmpipe.
1

Install the base package

The base install covers everything you need for 2D games: sprite rendering, 2D physics (pymunk), text, audio, tilemaps, and the CLI.
pip install keelpy
This pulls in the following transitive dependencies automatically:
PackagePurpose
numpyComponent storage (structured arrays)
modernglOpenGL rendering backend
glfwWindow creation and input
PillowImage loading (PNG, JPG, BMP, TGA)
watchdogAsset hot-reload file watcher
pymunk2D physics engine
freetype-pyFont rasterization
miniaudioAudio playback
2

Choose optional extras (if needed)

Keel ships two optional extras for features that require heavier or platform-restricted dependencies.
pip install keelpy[physics3d]
physics3d installs pybullet>=3.2 for the 3D physics bridge (setup_physics_3d). pybullet currently has pre-built wheels on Windows and a few older Python/platform combinations only. On Linux and macOS it must be compiled from source, which requires a C++ toolchain.tools installs imgui-bundle>=1.5 for the ImGui-powered world inspector (F1), frame profiler overlay (F2), and physics debug draw (F3). Keel supports both the 1.5.x and 1.9x+ module layouts of imgui-bundle, so pip installs whichever wheel is available for your Python version.
pybullet on macOS and Linux: keelpy[physics3d] may attempt to compile pybullet from source on non-Windows platforms. If you do not need 3D physics, omit this extra — 2D physics via pymunk works everywhere and is included in the base install.
3

Verify the install

Open a Python shell and confirm both the package and version are reachable:
import keel
print(keel.__version__)   # e.g. 0.8.5
A successful print means the engine, renderer, and all base dependencies loaded correctly.

​
Install from Source

If you want to contribute to Keel, use a pre-release build, or run the example scripts directly from the repository, install from a local clone: 
git clone https://github.com/VKSFY/keel
cd keel
pip install -e .
The -e flag installs the package in editable mode, so changes you make to the source are immediately reflected without reinstalling. To include both optional extras when working from source: 
pip install -e ".[physics3d,tools]"
Run the test suite to confirm everything is wired up correctly: 
pytest
The suite covers every system phase and runs in seconds on a modern machine.

​
Platform Notes

PlatformBase installphysics3dtools
Windows✅✅ (pre-built wheels)✅
macOS✅⚠️ Source build required✅
Linux✅⚠️ Source build required✅
import keel fails with “No module named ‘keel’”? This almost always means you installed the wrong package name. The PyPI distribution is keelpy; the import is keel. Run:
pip install keelpy
Then in your code:
import keel  # correct — NOT "import keelpy"
If you installed from a clone and still see the error, run pip install -e . from the repo root and check that no stray keel.py file is shadowing the package on your PYTHONPATH.

​
Upgrading

pip install --upgrade keelpy
To upgrade with extras: 
pip install --upgrade "keelpy[tools]"
Keel follows semantic versioning. Patch releases (e.g. 0.8.4 → 0.8.5) are backward-compatible bug fixes. Minor releases may introduce new APIs; deprecated APIs are kept for at least one minor version before removal.

Build docs developers (and LLMs) love

Get started for freeTalk to us