How to Use the chafa Command in Linux to Display Images and GIFs in the Terminal

Working in headless Linux environments or remote SSH sessions often means sacrificing visual feedback. When generating server analytics charts, reviewing automated camera captures, inspecting user uploads, or downloading media, sysadmins typically have to transfer files to a local workstation using SCP or SFTP just to verify their contents. Traditional command-line image viewers either require an active X11/Wayland display server or produce illegible, low-contrast ASCII art.

chafa (Character Art Facsimile) bridges this gap by rendering images and animated GIFs directly inside the terminal with remarkable clarity. Using advanced Unicode block symbols, 24-bit Truecolor ANSI palettes, and modern terminal graphics protocols like Sixel and Kitty graphics, chafa turns any terminal emulator into a high-speed graphics canvas.

How chafa Achieves High-Fidelity Terminal Graphics

Unlike basic ASCII converters that substitute simple letters for pixel brightness, chafa relies on sophisticated graphic algorithms:

• Sub-Pixel Unicode Glyph Fitting: chafa evaluates combinations of Unicode quarter-blocks, half-blocks, and sextant characters to simulate higher effective resolutions inside standard terminal character grids.
• Colour Space Optimisation: It maps image RGB values into the exact colour space supported by your terminal, including 24-bit Truecolor, 256-colour palettes, or classic 16-colour ANSI modes.
• Hardware Terminal Protocols: If your terminal supports Sixel, Kitty, or iTerm2 graphics protocols, chafa can bypass character blocks entirely and output raw bitmap graphics directly into the shell stream.
• Animated GIF Playback: chafa includes a built-in frame scheduler that plays animated GIFs smoothly directly inside the command line.

Installing chafa Across Linux Distributions

chafa is available in official repositories across all major Linux distributions.

Installing on Ubuntu, Debian, and Linux Mint

On modern Debian-based distributions, install chafa via APT:

sudo apt update
sudo apt install chafa

Installing on Fedora, RHEL, and CentOS

On Fedora and modern Enterprise Linux systems with EPEL enabled, install via DNF:

sudo dnf install chafa

Installing on Arch Linux and Manjaro

Arch Linux packages chafa in the extra repository:

sudo pacman -S chafa

Verifying the Installation

Confirm that the binary is functional and inspect the compiled feature set:

chafa --version

Displaying Images in the Terminal

To view an image, pass the file path directly as an argument to the chafa command:

chafa /path/to/image.jpg

chafa automatically detects your terminal window dimensions, calculates appropriate aspect ratios, samples the colour palette, and prints the rendered graphic directly into your shell output.

Controlling Output Dimensions and Sizing

By default, chafa scales the image to fit your current terminal window width and height. You can explicitly constrain output dimensions using character cell counts:

# Limit output to 60 columns wide and 30 rows high
chafa --size 60x30 diagram.png

# Constrain only the width while maintaining aspect ratio
chafa --size 80x sample.png

Constraining dimensions is particularly helpful when incorporating image previews into bash shell scripts, status dashboards, or terminal motd (message of the day) banners.

Playing Animated GIFs in the Terminal

One of chafa’s most impressive capabilities is rendering animated GIF files inline with accurate timing:

chafa animation.gif

The animation plays continuously in the terminal. Press Ctrl + C to stop playback and return to your prompt.

If you only want to inspect a specific number of animation cycles or duration, use the duration flag:

# Play the GIF for exactly 5 seconds before returning to the prompt
chafa --duration 5 animation.gif

Selecting Graphics Protocols and Formats

chafa supports several output modes depending on your terminal emulator’s technical capabilities (e.g. Alacritty, Kitty, WezTerm, Foot, or GNOME Terminal):

Format Flag	Mode Description	Typical Use Case
--format symbols	Unicode block and sextant characters (Default).	Universal compatibility across all modern terminal emulators.
--format sixels	True bitmap pixel rendering using DEC Sixel graphics.	High-definition graphic display in Foot, WezTerm, or XTerm.
--format kitty	Kitty terminal graphics protocol.	Native full-resolution GPU rendering in Kitty terminal.
--format iterm	Inline image protocol for iTerm2 and compatible clients.	SSH sessions connected from macOS iTerm2 workstations.

To force high-definition Sixel rendering on supported terminals, run:

chafa --format sixels photo.png

Integrating chafa with File Managers and Shell Tools

chafa pairs exceptionally well with terminal file managers like ranger, nnn, and yazi to deliver instant image previews when browsing folders.

You can also create a lightweight shell function in ~/.bashrc or ~/.zshrc that pipes images directly from the web:

webimg() {
    curl -s "$1" | chafa -
}

After sourcing your shell configuration, test the function by passing any public image URL:

webimg "https://example.com/logo.png"

chafa reads the incoming byte stream from standard input and renders the image immediately, providing a seamless visual workflow without opening an external browser.