catimg

Print a JPEG, PNG, or GIF to the terminal

$ catimg [path/to/file]

$ catimg -r 2 [path/to/file]

$ catimg -t [path/to/file]

$ catimg [-w|-H] [40] [path/to/file]

catimg [-c COLORS] [-d DIMENSIONS] [-g] [-h] [-k] [-s SCALE] [-t TIMEOUT] [-u] [-w WIDTH] [-H] [-X] [FILE]...

-c, --colors N
    Limit to N colors: 1 (monochrome), 2, 4, 8, 16, or 256

-d, --dimensions
    Print dimensions (width x height in pixels) and exit

-g, --gradient
    Enable smooth color gradients

-h, --help
    Show help message and exit

-k, --kitty
    Use Kitty graphics protocol (requires Kitty terminal)

-s N, --scale N
    Scale image by factor: 0.25, 0.5, 1, 2, or 4

-t MS, --timeout MS
    Graphics protocol timeout in milliseconds (default: 200)

-u, --unicode
    Use Unicode half/full blocks (default in most terminals)

-w N, --width N
    Set output width in characters

-H N, --height N
    Set output height in characters

-x, --sixel
    Use SIXEL graphics (requires sixel support)

catimg is a lightweight command-line utility that renders images in terminal emulators using techniques like Unicode block characters, sixel graphics, or the Kitty graphics protocol. It supports popular formats including JPEG, PNG, WebP, GIF (first frame), and APNG.

Ideal for headless servers or minimal environments, it bypasses the need for graphical viewers by approximating pixel data with colored blocks or native terminal graphics. Users specify dimensions, color depth, or scaling for optimal fit. It excels in true-color terminals like Kitty, iTerm2, or xterm-256color, but falls back to 256-color or 16-color modes.

Unlike ASCII art tools, catimg preserves image fidelity with gradients and dithering options, making it suitable for quick previews in scripts, tmux sessions, or SSH. Output is ephemeral, clearing on next command unless piped or scripted to persist.

Requires terminal with truecolor or 256-color support; poor results in basic terminals like xterm. Kitty/SIXEL modes need compatible terminal and libsixel. Large images may cause flicker or high CPU. No animation beyond GIF first frame.

JPEG, PNG, BMP, WebP, GIF (static), APNG, TIFF; uses libjpeg, libpng, etc.

apt install catimg (Debian/Ubuntu), pacman -S catimg (Arch), dnf install catimg (Fedora); or build from source: make && sudo make install.

Developed by Eduardo A. Bart (posva) in 2017 as a simple cat-like image viewer. Initial GitHub release supported basic block rendering; v2.5+ added Kitty, SIXEL, WebP. Now in repos like Arch, Debian, Fedora; actively maintained with 1k+ stars.

chafa(1), timg(1), jp2a(1), aac(1), sixel(1)