chafa

Render an image directly in the terminal

$ chafa [path/to/file]

$ chafa [[-c|--colors]] full [path/to/file]

$ chafa [[-c|--colors]] 16 --dither ordered [path/to/file]

$ chafa --symbols vhalf [path/to/file]

$ chafa [[-c|--colors]] none --symbols braille [path/to/file]

chafa [OPTION...] [FILE...]

-c, --color-space CS
    Select color space, e.g. wc, xterm, rxvt, truecolor

-f, --format FORMAT
    Output format: kitty, sixel, iterm2, unicode

-s, --size SIZE
    Output size, e.g. 80x40, tty (fit terminal), chars

-W, --width WIDTH
    Exact width in characters, cells, or pixels

-H, --height HEIGHT
    Exact height in characters, cells, or pixels

-p, --pixels WxH
    Source pixel size limit

-S, --symbols SET
    Symbol set: blocks, braille, all, limited

-d, --dither-mode MODE
    Dithering: ordered, noise, floyd-steinberg, none

-g, --dither-grain GRAINS
    Number of dither grains (1-16)

--animate[=MODE]
    Play animations: once, loop

-o, --optimize[=MODE]
    Optimize: speed, size, quality

-F, --font-glyphs
    Map to terminal font glyphs

--clear
    Clear screen before output

--insecure
    Disable ImageMagick security policies

-v, --version
    Display version info

-h, --help
    Show full help

Chafa is a fast, lightweight command-line tool for rendering images directly in terminals via Unicode block graphic characters, sixels, or graphics protocols like Kitty and iTerm2. It converts raster images (PNG, JPEG, GIF, WebP, AVIF, SVG) and animations into stylized art using advanced dithering techniques such as ordered dithering, noise dithering, and Floyd-Steinberg.

Supporting over 20 color spaces (from monochrome to 24-bit truecolor) and customizable symbol sets (blocks, Braille, smooth shades), Chafa adapts to terminal constraints like xterm, rxvt, or tmux. It uses backends like ImageMagick for broad format support, with options for stdin input, aspect ratio control, animation playback, and optimization modes balancing speed, quality, and size.

Ideal for shell scripts, IRC clients, status bars, or headless servers piping images to terminals. No GUI required; low memory footprint even for large files.

Quality varies by terminal font, size, and color support. Large/animated images may lag without -o speed. Requires Unicode; fallback to ASCII on basic terminals. ImageMagick backend may need config tweaks for exotic formats.

chafa image.png (default terminal fit)
chafa -s 80x24 -f sixel photo.jpg (sixel output)
cat image.gif | chafa --animate=loop -c truecolor (stdin animation)

Common: mono (1-bit), ansi (16-color), rxvt (88-color), kitty (truecolor), ntsc (video-optimized). Use chafa --list=cs.

blocks (full Unicode blocks), braille (compact), smoothed (gradient shades). List with chafa --list=symbols.

Created by Haukur H. Thorsson in 2018 as open-source (LGPL/MIT) on GitHub. Initial focus on Unicode dithering; v0.5 added sixels (2019). Evolved with AVIF/JXL support, Kitty protocol (v1.0, 2021), and polish in v1.14 (2024). Widely used in terminal tools.

timg(1), ueberzugpp(1), catimg(1), convert(1), ffmpeg(1)