Skip to content

Installation

Tesserae Engine ships as a compiled Python extension module (tre._core, built with PyO3/maturin) plus a thin pure-Python package (tre) on top of it. There are two ways to get it: install a pre-built wheel, or build one yourself from source.

Requirements

  • Python 3.12 or newer (CPython; on Linux also free-threaded 3.14t/ 3.15t builds — see the supported set below)
  • Linux (x86_64), macOS (arm64), or Windows (x64); other platforms build from source

Option 1: install from PyPI

pip install tesserae-engine

Tesserae Engine is published on PyPI as tesserae-engine — the name tre there belongs to an unrelated project. The import name is tre:

import tre

A dependency on it is written the same way, for example dependencies = ["tesserae-engine>=0.4.2"] in a pyproject.toml.

Upgrading from a tre-... wheel

Releases up to v0.3.5.1 installed a distribution named tre. pip treats tesserae-engine as a different project, so it leaves the old one in place, and both then own the tre package — a later pip uninstall tre would delete files tesserae-engine needs. Remove the old one first:

pip uninstall tre
pip install tesserae-engine

Option 2: install a wheel from a GitHub release

Every tagged release publishes real, verified wheels, the same files PyPI carries — a source distribution, plus:

  • Linux — portable manylinux_2_17/manylinux2014 wheels, built inside the real manylinux Docker container (not just locally repaired). The container ships several real CPython interpreters plus PyPy, and the build picks up every one it finds (maturin-action's own --find-interpreter) rather than a hand-maintained list, filtered by the project's requires-python (3.12 or newer): CPython 3.12–3.15, including the free-threaded 3.14t/3.15t builds. (Through 0.5.1 the set also had CPython 3.9–3.11 and PyPy 3.11.)
  • macOS (arm64) and Windows — one wheel per CPython version in an explicit, hand-maintained matrix (currently 3.12–3.14) via actions/setup-python — no free-threaded or PyPy builds on these two platforms; neither ships a container with several interpreters pre-installed the way the Linux build's own container does.

The GitHub Release also carries a standalone, non-wheel-packaged Linux/CPython 3.14 extension module (_core.cpython-314-x86_64-linux- gnu.so) for tooling that consumes the compiled module directly rather than through pip.

Download the wheel matching your platform and interpreter from the latest release and install it directly:

pip install ./tesserae_engine-0.4.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Releases up to v0.3.5.1 name their files tre-<version>-...; they install the same tre package.

Note

pip install tre installs the unrelated tre project from PyPI, not this one.

Option 3: build from source

You'll need a Rust toolchain (see rust-toolchain.toml for the exact pinned version — rustup picks it up automatically; the minimum supported Rust version is 1.90) and maturin. On Linux you also need pkg-config and the fontconfig, xkbcommon, Wayland, and X11 development packages — on Debian or Ubuntu:

sudo apt-get install pkg-config libfontconfig1-dev libxkbcommon-dev \
    libwayland-dev libx11-dev libxrandr-dev libxi-dev libxcursor-dev \
    libxinerama-dev libudev-dev

Then:

git clone https://github.com/mindderivative/tre.git
cd tre
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install maturin
maturin develop --release

maturin develop compiles the Rust extension and installs it directly into your active virtual environment in editable form — the fastest loop for local development. Run any script under examples/ to confirm it worked:

python examples/showcase.py

Building a portable wheel yourself

maturin build --release alone does not produce a portable wheel on most Linux dev machines — without an explicit target it silently falls back to a bare, non-redistributable linux platform tag. Building a real, portable manylinux wheel from an ordinary Linux dev host needs either:

  • maturin[zig], cross-compiling with an explicit compatibility target:
pip install 'maturin[zig]'
maturin build --release --zig --compatibility manylinux_2_38

(Zig itself also needs to be on PATH as zig — the ziglang PyPI package installs a python-zig entry point, not a plain zig binary, so a one-line shim script is needed on top of it.)

  • A real manylinux container, the same way this project's own release CI does it (see .github/workflows/wheels.yml): a genuinely older glibc baseline inside the container achieves a substantially broader, more portable tag automatically, with no zig cross-compilation needed at all.

Verifying the install

import tre
print(tre.App, tre.Window, tre.Node)

If that import succeeds, you're ready for Getting Started.