par-textual-image 0.1.0

Textual widget for full-color terminal image rendering (Kitty TGP, Sixel, iTerm2, half-block)

PAR Textual Image

Table of Contents

• About
• Features
• Supported Protocols
• Prerequisites
• Installing
• Quick Start
• API Reference
• Environment Variables
• Protocol Detection
• Installing for dev mode
• Contributing
• License

About

PAR Textual Image is a Textual widget (TerminalImage) that renders full-color images in a terminal TUI by auto-detecting and using the best available terminal graphics protocol. The library was built with Textual, Rich, and Pillow. It runs on all major terminals that support Kitty TGP, Sixel, iTerm2 inline images, or falls back to half-block ANSI rendering.

Features

• Auto-detection — probes for Kitty TGP, Sixel, and iTerm2 support at startup; falls back to half-block rendering
• Manual override — force_protocol("kitty" | "sixel" | "iterm2" | "halfblock")
• Multiple input types — file path, PIL Image, or BytesIO
• Protocol-aware sizing — uses terminal cell pixel dimensions for pixel-based protocols
• Seamless Textual integration — works as a drop-in widget with compose() / mount()
• Type-safe — fully typed codebase with strict pyright checking

Supported Protocols

Protocol	Method	Quality	Terminal Support
Kitty TGP	Virtual placement	Full color	Kitty, KiTTY
Sixel	DCS escape sequences	Full color	xterm, mintty, Windows Terminal, others
iTerm2	OSC 1337 inline	Full color	iTerm2
Half-block	Unicode + ANSI colors	Medium	Any terminal with Unicode support

Prerequisites

• Python 3.13 or newer
• A terminal supporting at least one of the above protocols (half-block works everywhere)

Installing

Using pip

pip install par-textual-image

Using uv

uv add par-textual-image

Using pipx

pipx install par-textual-image

Quick Start

from textual.app import App, ComposeResult
from par_textual_image import TerminalImage

class ImageViewer(App):
    def compose(self) -> ComposeResult:
        yield TerminalImage("photo.png")

if __name__ == "__main__":
    ImageViewer().run()

Force a specific protocol

widget = TerminalImage()
widget.force_protocol("sixel")
widget.set_image("photo.png")

Use a PIL Image directly

from PIL import Image
img = Image.open("photo.png").resize((200, 100))
widget = TerminalImage(img)

API Reference

TerminalImage

The main Textual widget. Accepts an optional image source on construction.

Method	Description
TerminalImage(source=None)	Create widget with optional file path, Image, or BytesIO
set_image(source)	Set / replace the current image
force_protocol(name)	Switch protocol ("kitty", "sixel", "iterm2", "halfblock")
protocol_info	Property returning (protocol_name, renderer_name)

detect_protocol()

Auto-detect the best available protocol. Returns a string like "kitty", "sixel", "iterm2", or "halfblock". Result is memoized — call once at startup.

query_cell_size()

Query the terminal cell pixel dimensions. Returns (width, height).

Environment Variables

Variable	Description
PAR_TERM_GRAPHICS	Force a specific protocol (kitty, sixel, iterm2, halfblock)
TEXTUAL_CELL_WIDTH	Override detected cell width in pixels
TEXTUAL_CELL_HEIGHT	Override detected cell height in pixels

Protocol Detection

Detection priority:

1. PAR_TERM_GRAPHICS env var (if set and valid)
2. iTerm2 env vars (TERM_PROGRAM=iTerm.app or LC_TERMINAL=iTerm2)
3. Kitty TGP probe (queries the terminal, 100ms timeout)
4. Sixel probe (DA1 query checks for 4)
5. Fallback: halfblock

Installing for dev mode

Clone the repo and run the setup make target. Note uv is required.

git clone https://github.com/paulrobello/par-textual-image
cd par-textual-image
make setup

Contributing

See CONTRIBUTING.md for development setup, code style, commit conventions, and the pull request process.

License

This project is licensed under the MIT License — see the LICENSE file for details.