Python bindings for Ratatui, implemented in Rust with PyO3.
Version 0.3.0 targets Ratatui 0.30.2 and supports Python 3.10+.
pip install pyratatuiBuilding from source requires Rust 1.88 or newer and maturin:
pip install maturin
maturin develop --releasefrom pyratatui import Block, Color, Paragraph, Style, run_app
def ui(frame):
frame.render_widget(
Paragraph.from_string("Hello! Press q to quit.")
.block(Block().bordered().title("Hello"))
.style(Style().fg(Color.cyan())),
frame.area,
)
run_app(ui, on_key=lambda ev: ev.code == "q")More examples live in examples/. Each one is a small runnable program:
python examples/hello_world.py
python examples/dashboard.pyterm.draw takes a callback that receives the frame. Snapshot loop state
into default arguments so each frame renders its own tick:
with Terminal() as term:
while True:
count = state["count"]
term.draw(lambda frame, _count=count: render(frame, _count))
ev = term.poll_event(timeout_ms=100)
if ev and ev.code == "q":
breakQuitting is always explicit — run_app stops when on_key returns True,
and manual loops break on whatever key they choose.
The public API is exported from the top-level package:
from pyratatui import (
Terminal, # terminal driver (also AsyncTerminal, run_app, run_app_async)
Frame, # render surface handed to the draw callback
KeyEvent, # keyboard events from poll_event
Layout,
Constraint,
Direction,
Alignment,
Rect,
Style,
Color,
Modifier,
Span,
Line,
Text,
Block,
Paragraph,
List,
Table,
Gauge,
BarChart,
Sparkline,
Scrollbar,
Tabs,
Clear,
Chart,
Canvas,
Map,
Monthly,
TextPrompt,
TextState,
prompt_text, # input helpers
Buffer, # off-screen surface (testing)
)Widgets are Ratatui's built-in set plus thin Chart, Canvas, Map, and
calendar (Monthly) bindings. Types carry docstrings, and
python/pyratatui/_pyratatui.pyi ships full type annotations.
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
maturin develop
pytest # Python tests (includes pty-based terminal tests)
cargo test # Rust tests
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check
ruff check . && ruff format --check .See CONTRIBUTING.md for details.
- Special thanks to the Ratatui project and designer Pavel Fomchenkov for the Ratatui logo.
- Also, thanks to everyone who has contributed to
pyratatui!
MIT — see LICENSE.