imgcat

library0.6.0pypypi✓ verified 90d ago

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.

devops observability

pip install imgcat

github ↗package ↗

INSTALL

IMPORT

SIG · IMGCAT

imgcat

devopspythonv0.6.0

Install

2.9s avg

Import

102ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.980 runs

installs and imports cleanly · install 0.0s · import 0.105s · 19.4MB

glibc

py 3.10–3.980 runs

installs and imports cleanly · install 2.9s · import 0.099s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

imgcat

✓ from imgcat import imgcat

IPython Magic

✓ %load_ext imgcat

✗ import imgcat.ipython_magic

IPython magic commands are loaded using '%load_ext' not direct import.

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)

imgcat --version

Debug

Known issues

breakingPython 2 support has been dropped.

fix

Upgrade to Python 3.6 or newer. Previous versions (<=0.5.0) supported Python 2.

affects: >=0.6.0

gotchaImages 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.

affects: All versions

gotchaNumPy 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)`.

affects: All versions

gotchaMatplotlib 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.

affects: <0.6.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'imgcat'

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).

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

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'

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.

Upgrade

Version history

0.6.0latest on PyPI · released Nov 21, 2024

Audit

Dependencies

PillowrequiredRequired for image file format handling and general image processing.

numpyrequiredRequired for array handling and numerical image data processing.

torchoptionalOptional: Enables direct display of PyTorch tensors.

jaxoptionalOptional: Enables direct display of JAX arrays.

tensorflowoptionalOptional: Enables direct display of TensorFlow eager tensors.

matplotliboptionalOptional: Enables imgcat as a matplotlib backend.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wookayin/python-imgcat ↗

packagehttps://pypi.org/project/imgcat/ ↗