imgcat

Display an image on the command-line

$ imgcat [path/to/file]

imgcat [options] <file>
or
<some_command> | imgcat [options]

--width <N>
    Sets the width of the displayed image. <N> can be a number of columns, pixels, or a percentage (e.g., '50%').

--height <N>
    Sets the height of the displayed image. <N> can be a number of lines, pixels, or a percentage.

--align <value>
    Specifies horizontal alignment for the image. Common values include 'left', 'center', or 'right'.

--preserve-aspect-ratio
    Forces the image to maintain its original aspect ratio, potentially overriding explicit width/height settings.

--filename <name>
    When reading image data from stdin, provides a filename hint to the terminal. Useful for display or saving purposes.

imgcat is a utility that enables the display of images directly within certain modern terminal emulators, such as iTerm2 and Kitty. Instead of opening an external image viewer, imgcat leverages special terminal escape codes (e.g., iTerm2's image protocol or Kitty's graphics protocol) to render image data inline.

This functionality is particularly useful for quickly previewing images without interrupting a command-line workflow, for displaying visual output from scripts, or for integrating image viewing into shell environments. It processes image files and converts them into a format that the compatible terminal can interpret and render as a graphical element within the text-based interface. It typically supports common image formats like JPEG, PNG, and GIF.

imgcat is not a standard POSIX command; its availability and functionality depend entirely on the terminal emulator being used. It primarily functions with iTerm2, Kitty, and some other niche terminals that support specific image display protocols. Users of standard terminals like Gnome Terminal, Konsole, or xterm will typically not see images but rather sequences of control characters or raw binary data. Performance can vary based on image size, terminal, and system resources.

The primary prerequisite for using imgcat is a terminal emulator that supports its underlying image display protocol. The most widely known implementations are found in iTerm2 (using its proprietary image protocol) and Kitty (using its graphics protocol). Other terminals, like WezTerm, are also developing similar capabilities. Without a compatible terminal, imgcat will not display images correctly.

imgcat typically reads image data, encodes it (often Base64 or similar), and then wraps it in special terminal escape sequences (e.g., OSC 1337 ; File=... ; base64_data_here ; BEL for iTerm2 or CSI _G... for Kitty). These sequences instruct the terminal to interpret the encoded data as an image and render it at the current cursor position.

imgcat originated as part of iTerm2's shell integration scripts, allowing users to display images directly within the terminal window. Its success and utility led other terminal emulators, notably Kitty, to develop their own, often compatible or similarly purposed, image display protocols and utilities. It represents a significant step in blurring the lines between traditional text-based terminal interaction and richer graphical displays.

viu(1), feh(1), sxiv(1), cat(1)