Working on headless Linux servers, remote cloud instances over SSH, or within pure command-line environments usually means giving up visual image previews. Historically, developers relied on basic ASCII art utilities like caca or primitive framebuffer tools that produced blurry, unreadable character blobs. However, modern terminal emulators support sophisticated graphical features, including 24-bit true colour, Unicode block drawing symbols, and high-performance raster protocols like Sixel and Kitty graphics. To take full advantage of modern terminal display capabilities, Linux developers turn to Chafa. Chafa is a high-performance terminal graphics generator that converts images, animations, and document previews into crisp terminal graphics.
What Is Chafa and How Does It Render Graphics?
Unlike basic ASCII generators that simply map image brightness to letters, Chafa employs advanced image quantization and geometric symbol matching:
- Sub-Pixel Unicode Block Slicing: Evaluates image colour gradients and fits optimal Unicode fractional block elements (e.g.
▀,▄,▌,▐, quadrant blocks), doubling or quadrupling visual resolution. - Multi-Protocol Support: Seamlessly switches between ANSI text art, 24-bit Truecolor, six-colour palettes, Sixel graphics, and the native Kitty graphics protocol.
- Animated GIF and Video Playback: Renders animated GIFs directly in the terminal scrollback buffer with real-time frame rate controls.
- Fast Multi-Threaded Conversion: Utilizes SIMD vectorization and multi-core processor threads to convert megapixel graphics in milliseconds.
- Piping and Script Integration: Works seamlessly with utilities like
curl,fzf, and terminal file managers (Yazi, Ranger).
Installing Chafa Across Linux Distributions
Chafa is available in the official package repositories of all major Linux distributions.
Method 1: Installing on Ubuntu, Debian, and Linux Mint
sudo apt update
sudo apt install -y chafaMethod 2: Installing on Fedora and RHEL
sudo dnf install -y chafaMethod 3: Installing on Arch Linux and Manjaro
sudo pacman -S --noconfirm chafaConfirm that your installation is complete by checking the version:
chafa --versionBasic Image Viewing in the Terminal
To render any local image (JPEG, PNG, WebP, SVG, TIFF), pass the file path to chafa:
chafa screenshot.pngChafa inspects your active terminal window dimensions and automatically scales the output to fit cleanly without wrapping or breaking lines.
Piping Images Directly from the Web
You can preview remote web graphics without saving them to your hard drive first by piping curl output:
curl -s "https://digitash.com/assets/logo.png" | chafa -Playing Animated GIFs in the Terminal
Chafa natively decodes and plays animated GIF files directly on your command line:
chafa animation.gifBy default, animations loop indefinitely. To restrict playback to a specific duration or cycle count, use the --duration flag:
chafa --duration 5s animation.gifFine-Tuning Quality, Size, and Color Modes
You can customize how Chafa translates pixels into characters depending on terminal capabilities:
1. Forcing High-Resolution Sixel or Kitty Graphics
If you use a modern terminal emulator supporting Sixel or Kitty (e.g. Kitty, WezTerm, Foot, Alacritty with patches):
# Force Kitty graphics protocol (lossless raster)
chafa -f kitty photo.jpg
# Force Sixel protocol
chafa -f sixel photo.jpg2. Adjusting Dimensions and Aspect Ratio
Specify exact row and column dimensions using -s (size):
chafa -s 80x25 diagram.png3. Selecting Color Modes for Legacy SSH Sessions
When connecting over low-bandwidth serial lines or legacy 256-colour terminals:
# Force 256-colour palette
chafa -c 256 image.png
# Force 16-colour ANSI mode
chafa -c 16 image.pngIntegrating Chafa with Terminal File Managers
Chafa is widely deployed as the visual preview engine inside terminal file managers like yazi and ranger. When browsing image assets, these managers invoke chafa in background child processes to display live thumbnail previews in the right-hand inspection column.