---
id: imgcat
version: "0.6.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# imgcat — imgcat as Python API and CLI

License: permissive · Maintenance: aging · Downloads: 197.6K/mo

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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: high
- Maintenance: aging
- Downloads: 197.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

terminal image display, iterm2 imgcat python, show images in terminal, matplotlib terminal backend, wezterm image rendering, terminal-graphics, matplotlib-backend, cli-utility

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