imgcat

What it is and what it does

imgcat is a Python CLI and library that renders images directly in terminal emulators that support inline image protocols. It works with iTerm2, WezTerm, and tmux (with version-specific caveats), and can display images from files, stdin, numpy arrays, PIL Image objects, and matplotlib figures. The package also provides a matplotlib backend so that plotting code can render directly to the terminal instead of to a window or file.

The core use case is interactive terminal workflows where you want to see image output without leaving the shell or opening external viewers. It has no runtime dependencies, making installation straightforward on systems where the terminal emulator already supports the protocol. The main constraint is terminal compatibility—the feature only works in emulators that implement iTerm2's inline image protocol or WezTerm's equivalent.

Use it for:

• Display matplotlib plots directly in the terminal during interactive data exploration or scripting.
• View image files from the command line without opening an external image viewer.
• Render numpy arrays and PIL images inline in a terminal REPL or Jupyter notebook.
• Use as a matplotlib backend in scripts to capture plot output to the terminal instead of a file.
• Pipe image data through stdin to imgcat for quick preview in shell pipelines.

Worth the install?

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

Displays images in iTerm2, WezTerm, and tmux by rendering them directly in the terminal via a Python CLI and API.

Yes, if you use iTerm2, WezTerm, or tmux and want inline image display in your terminal. The package has no runtime dependencies, making it lightweight to install. However, the aging maintenance status and high install friction (source-only distribution) mean you should verify compatibility with your specific terminal version before relying on it for critical workflows. Not useful outside compatible terminal emulators.

Install

imgcat on PyPI

pip install imgcat

uv add imgcat

poetry add imgcat

Installing imgcat

Before you install

High install friction: source distribution only. Maintenance is aging—631 days since last release, though repository remains active with recent commit on 2025-04-26.

License in practice

MIT license (permissive) imposes no restrictions on use, modification, or distribution.

Quickstart

pip install imgcat

from imgcat import imgcat
imgcat(open("./local_image.png"))

Requires a terminal emulator that supports iTerm2's inline image protocol (iTerm2, WezTerm, or tmux with version-specific configuration).

Verify before relying

• Whether the package works reliably with current versions of iTerm2 and WezTerm given the aging maintenance status.
• Specific tmux version compatibility constraints beyond the notes about tmux 2.5+ and 3.3a.
• Whether numpy and matplotlib are truly optional or required for core functionality.

Package facts

Evidence: imgcat-0.6.0.tar.gz

Keywords: imgcat, iterm2, matplotlib

Tags

More Terminals packages