Installation

For most users, installation is just one pip command. Source builds are only necessary if you want to work on the project itself or need a custom native build.

Recommended PathStart with the prebuilt wheel via pip. Only switch to a source build if pip install tuix-core fails for your platform or if you are developing TUIX Core itself.

Requirements

Python 3.10 or newer
A terminal with ANSI escape sequence support
A C compiler only if you plan to build from source

pip

pip install tuix-core

Prebuilt wheels are available for Python 3.10+ on Windows (x86, AMD64), Linux (x86_64, i686, aarch64), and macOS (x86_64, arm64).

Source Build

Building from source requires Cython >= 0.29 and a C compiler. The build compiles the Cython extension (_tuix_cy) and links 23 C source files.

pip install cython>=0.29
pip install .

Custom CompilationThe source distribution includes all C files. Advanced users can compile the C library manually to include optional modules (such as the halfblock renderer or cache manager) that are not part of the default build.

Build from Source Only If You Need ItIf you only want to use TUIX Core, the source build path adds unnecessary moving parts. Prefer the wheel unless you need to debug compilation or modify native code.

Dependencies

TUIX Core has no external Python dependencies. All imports are from the Python standard library: os, sys, time, ctypes, and typing.

Platform Notes

WindowsInput is captured via ReadConsoleInputW with native KEY_EVENT and MOUSE_EVENT records. ANSI escape sequence rendering works in cmd.exe, PowerShell, and Windows Terminal.

LinuxInput is captured via raw mode (termios/tty) with SGR mouse parsing. The build links against pthread for the input listener thread.

macOSSame POSIX input path as Linux. Requires a terminal that supports ANSI escape sequences and ideally truecolor.

Verify Installation

Run this short snippet before building a full app. It checks that the native extension loads and that the core can initialize cleanly.

from tuix.core import engine
engine.init()
print("TUIX Core v0.3 loaded successfully")
engine.shutdown()

ReadyIf no errors appear, TUIX Core is installed correctly. Proceed to the First Widget tutorial.

Common Problems

pip install fails on an unsupported platform: try the source build path and verify that your compiler toolchain works.
The terminal shows broken colors: switch to a modern ANSI-capable terminal such as Windows Terminal, a recent PowerShell, or a standard Linux/macOS terminal emulator.
engine.init() raises immediately: verify that the wheel or extension was installed for the same Python version you are currently using.