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

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.

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

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.