textual-image

What it is and what it does

textual-image bridges terminal graphics capabilities and Python TUI frameworks by providing both Rich renderables and Textual widgets that display images in modern terminal emulators. It leverages Kitty's Terminal Graphics Protocol and Sixel graphics standards to render images natively, with automatic fallback to Unicode character-based rendering for terminals that lack graphics support.

The package targets developers building terminal user interfaces who need to embed images—charts, diagrams, photographs—directly in their applications. It depends on pillow for image processing and rich for terminal rendering integration, and requires Python 3.12 or later. Terminal support varies significantly: Kitty, WezTerm, iTerm2, and several others work out of the box, while some popular terminals like GNOME Terminal and Windows Console lack the necessary graphics protocols entirely.

Use it for:

• Display charts or plots in terminal dashboards built with Textual
• Render image previews in terminal file managers or CLI tools
• Show screenshots or diagrams in terminal-based documentation viewers
• Embed logos or icons in terminal application UIs
• Display scientific or data visualization output directly in terminal workflows

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Renders images directly in terminal emulators using Textual widgets and Rich renderables, with support for Kitty's Terminal Graphics Protocol, Sixel graphics, and Unicode fallback.

Yes, if your target terminal supports Sixel or Kitty graphics protocols. The package is actively maintained, has no known vulnerabilities, and low install friction. However, terminal compatibility is critical—check the support matrix first, as many common terminals (GNOME Terminal, Windows Console, Warp) are not supported. For terminals that do support the required protocols, this is a solid choice for image rendering in TUIs.

Install

textual-image on PyPI

pip install textual-image

uv add textual-image

poetry add textual-image

Installing textual-image

Before you install

Low friction install with just two runtime dependencies (pillow and rich). Active maintenance with recent commits and no known vulnerabilities.

License in practice

Licensed under LGPLv3+, a copyleft license. You may use and modify the package freely, but any derivative works must also be distributed under compatible terms.

Quickstart

pip install textual-image

from textual_image.rich import Image
from rich.console import Console

console = Console()
image = Image('path/to/image.png')
console.print(image)

Requires a terminal emulator that supports either Kitty's Terminal Graphics Protocol or Sixel graphics; fallback to Unicode rendering works in any terminal but with reduced quality.

Verify before relying

• Whether the package works reliably across all listed terminal emulators or if some have known rendering issues beyond the support matrix
• Performance characteristics when rendering large or high-resolution images in different terminals
• Whether optional Textual widget dependencies are required for core functionality or truly optional

Package facts

Evidence: textual_image-0.13.2-py3-none-any.whl

Tags

More Libraries packages