---
id: textual-image
version: "0.13.2"
license: unclear
license_treatment: copyleft
maintenance: active
---

# textual-image — Render images via Kitty's Terminal Graphics Protocol with Rich and Textual

License: copyleft · Maintenance: active · Downloads: 174.5K/mo

## 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 above — 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

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

- License: not declared (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 174.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

terminal image rendering, kitty graphics protocol, sixel terminal display, textual image widget, rich image renderable, terminal graphics display, unicode image fallback, terminal-graphics, tui-framework, image-rendering

[View on SkillFed](https://skillfed.io/packages/textual-image) · [View on PyPI](https://pypi.org/project/textual-image/)