Chafa – terminal graphics image viewer

In Operation

To view high resolution images in our terminal, we’re running the Kitty terminal emulator.


Chafa automatically detects we are using a terminal emulator that supports the Kitty Graphics Protocol, and outputs this high resolution image. The software also supports iTerm2, Sixels, and Unicode mosaics.

Chafa supports most popular image formats, including animated GIFs.

Images can be dithered to produce perceptually smoother gradients. Two strategies are supported: “ordered” aka “bayer”, which applies a uniform intensity-modulating pattern, and “diffusion” aka “fs” (Floyd-Steinberg), which calculates the color deviance at each pixel and compensates by spreading a correction factor to its neighbors.

Other features include:

  • Combines Unicode symbols from multiple selectable ranges for optimal output.
  • Fullwidth character support, e.g. Chinese, Japanese, Korean.
  • Glyphs can be loaded from any font file supported by Freetype (TTF, OTF, PCF, etc).
  • Multiple color modes, including Truecolor, 256-color, 16-color and simple FG/BG.
  • There’s also an 8-color mode. It’s possible to enable visual emulation of Teletext Level 1 and similar systems.
  • RGB and DIN99d color spaces for improved color picking.
  • Fill symbols – these let you fill flat spaces with symbols that modulate the perceptual color.
  • Alpha transparency support in any color mode, including in animations.
  • Preprocessing – boosts contrast and saturation in reduced-color modes. This makes most images more legible and can improve color accuracy.
  • Work factor – a measure of how much CPU time and memory to spend refining the output. The factor ranges from 1 to 9. Lower values are fast, but produce rougher output, while the highest values are slower but more precise. The default factor is 5.
  • Option to stretch an image to fit the output dimensions.
  • Works with most modern and classic terminals and terminal emulators.
  • Documented, stable C API.
  • Fast and lean: SIMD optimized, multithreaded.
  • Suitable for terminal graphics, ANSI art composition and even black & white print.


Chafa is a very useful image viewer with good support for a wide range of terminals and a fairly wide range of command options.

There’s lots to like here. Animations are particularly well implemented.

Overall, Chafa runs timg pretty close as our recommended terminal image viewer. If you can live without timg’s grid view (which is really useful), Chafa may be everything you need for viewing high resolution images in a terminal.

Support: GitHub Code Repository
Developer: Hans Petter Jansson
License: GNU Lesser General Public License v3.0

Chafa is written in C. Learn C with our recommended free books and free tutorials.

Pages in this article:
Page 1 – Introduction / Installation
Page 2 – In Operation / Summary