imgcat Python Library

0.6.0 · active · verified Thu Apr 16

imgcat provides a Python API and CLI tool to display images directly in supporting terminals (like iTerm2 or Kitty) using their graphics protocols. The current version is 0.6.0, released in November 2024, with major updates occurring periodically to add features and improve compatibility.

Common errors

```
ModuleNotFoundError: No module named 'imgcat'
```
cause The imgcat library is not installed in your current Python environment.

fix Run `pip install imgcat` to install the library.
```
Image does not display in terminal (no error, just blank output or text output).
```
cause Your terminal emulator does not support the necessary image protocols (iTerm2/Kitty graphics).

fix Switch to a compatible terminal like iTerm2, Kitty, or WezTerm, or ensure your terminal is configured to enable image display.
```
TypeError: Invalid input type for imgcat. Expected bytes, path-like, numpy.ndarray, PIL.Image.Image, or torch.Tensor/tf.Tensor/jax.Array
```
cause The object passed to `imgcat` is not one of the supported image data types.

fix Convert your data to a supported type, e.g., a NumPy array, a PIL Image object, or a path to an image file. Ensure you have the necessary optional dependencies installed for tensor types.
```
AttributeError: module 'imgcat' has no attribute 'ipython_magic'
```
cause You are trying to import the IPython magic directly, which is not how it's loaded.

fix In an IPython/Jupyter environment, use the magic command `%load_ext imgcat` to enable the `%imgcat` magic.

Warnings

breaking Python 2 support has been dropped.
Fix: Upgrade to Python 3.6 or newer. Previous versions (<=0.5.0) supported Python 2.
gotcha Images will only display in terminals that support iTerm2 or Kitty graphics protocols.
Fix: Use a compatible terminal emulator such as iTerm2, Kitty, or WezTerm. Check your terminal's documentation for image display support.
gotcha NumPy arrays passed to `imgcat` expect values in the 0-255 range (for `uint8`) or 0-1 range (for `float`). Incorrect ranges can lead to distorted or dark images.
Fix: Ensure your NumPy array data is scaled correctly (e.g., `np.uint8` with values 0-255, or `float` with values 0-1). For example, `(np.random.rand(H, W, 3) * 255).astype(np.uint8)`.
gotcha Matplotlib integration issues were present in older versions.
Fix: Upgrade to `imgcat` version 0.6.0 or newer to benefit from fixes for matplotlib integration problems.

Install

pip install imgcat Install base library
pip install imgcat[torch] Install with PyTorch support
pip install imgcat[jax] Install with JAX support
pip install imgcat[tensorflow] Install with TensorFlow support

Imports

imgcat
```
from imgcat import imgcat
```
IPython Magic
wrong:
```
import imgcat.ipython_magic
```
correct:
```
%load_ext imgcat
```
IPython magic commands are loaded using '%load_ext' not direct import.

Quickstart

This example shows how to import and use the `imgcat` function to display a randomly generated NumPy array directly in a compatible terminal. Ensure your terminal (e.g., iTerm2, Kitty, WezTerm) supports iTerm2/Kitty graphics protocols.

from imgcat import imgcat
import numpy as np

# Display a random numpy array as an image
# (100x100 pixel RGB image with values 0-255)
imgcat(np.random.randint(0, 256, size=(100, 100, 3), dtype=np.uint8))

# In an IPython/Jupyter environment, you can also use:
# %load_ext imgcat
# %imgcat np.random.rand(100, 100, 3)

view raw JSON →