tiv

Display images in terminal using ANSI

TLDR

Display an image

$ tiv [image.png]

Display with specific width

$ tiv -w [80] [image.jpg]

Display with specific height

$ tiv -h [24] [image.png]

Display multiple images

$ tiv [image1.png] [image2.jpg] [image3.gif]

Show a directory as a thumbnail grid

$ tiv [/path/to/images/]

Use a custom number of thumbnail columns

$ tiv -c [5] [/path/to/images/]

Use 256-color mode (e.g. macOS Terminal)

$ tiv -2 [image.png]

SYNOPSIS

tiv [options] image [image...]

tiv (Terminal Image Viewer) displays images directly in the terminal using RGB ANSI escape codes and Unicode block graphics characters. It maps each 4x8 pixel cell to the block character and foreground/background colors that best approximate the original.Images are loaded with the bundled CImg library: PNG support is compiled in, while other formats (JPEG, GIF, BMP, and more) are handled by invoking ImageMagick's `convert`. Images are scaled to fit the terminal while preserving aspect ratio.When given a directory or more than one file, tiv switches to 'dir' mode and renders a grid of thumbnails (override with -f/-d). For best results, use a terminal with true color (24-bit) support. The -2 256-color mode works on older terminals but produces lower quality output. Block characters provide roughly 2x vertical resolution compared to standard characters.

PARAMETERS

-w num

Set the maximum output width to num characters.

-h num

Set the maximum output height to num lines.

-2, --256

Use 256 colors instead of 24-bit true color. Needed to display properly on macOS Terminal.

-0

No block character adjustment: always use the top half block character.

-c num

Number of thumbnail columns in 'dir' mode (3 by default).

-d, --dir

Force 'dir' (thumbnail grid) mode. Selected automatically for more than one input.

-f, --full

Force 'full' mode. Selected automatically for a single input.

-C hex

Use hex color (0xFFFFFF white by default) as the background for transparent PNG/GIF.

-x

Use new Unicode Teletext/legacy characters (experimental).

--help

Display help information.

CAVEATS

Quality depends on terminal capabilities and font. True color terminal support gives the best results. Non-PNG formats require ImageMagick to be installed. Animated GIFs display only the first frame. Results vary significantly between terminal emulators.

HISTORY

tiv is the C++ TerminalImageViewer by Stefan Haustein, a lightweight way to preview images without leaving the terminal. It renders with RGB ANSI codes and Unicode block characters and is popular among developers who work primarily in terminals. Several unrelated tools also ship a `tiv` binary, so behavior can differ between installations.

tiv