chafa
Convert images to terminal-based art
TLDR
Render an image directly in the terminal
Render an image with 24-bit color
Improve image rendering with small color palettes using dithering
Render an image, making it appear pixelated
Render a monochrome image with only braille characters
SYNOPSIS
chafa [OPTIONS] [FILE...]
PARAMETERS
-f, --format NAME
Specifies the output format and color mode (e.g., 24bit, 256, ansi, sixels). Auto-detected if not specified.
-s, --size COLUMNSxROWS
Sets the exact output size in characters. Aspect ratio is maintained unless explicitly overridden.
-w, --width COLUMNS
Sets the maximum output width in characters, maintaining the image's aspect ratio.
-H, --height ROWS
Sets the maximum output height in characters, maintaining the image's aspect ratio.
-c, --colors MODE
Forces a specific color mode (e.g., 1 for monochrome, 16, 256, 24bit). This overrides auto-detection.
-d, --dither METHOD
Selects the dithering algorithm to use (e.g., auto, none, floyd-steinberg, ordered, random).
-C, --charset NAME
Chooses the character set to render the image (e.g., auto, full, symbols, half-block, block, ascii, braille).
-o, --output FILE
Writes the character art output to a specified file instead of standard output.
--center
Centers the output horizontally within the current terminal width.
--version
Displays version information for chafa and exits.
--help
Displays a comprehensive help message with all options and exits.
DESCRIPTION
chafa is a powerful command-line utility designed to transform graphical images into highly detailed character art, suitable for display in a terminal. It supports a wide array of output modes, including true color (24-bit), 256-color, 16-color, ANSI, and monochrome, making it versatile for various terminal environments. Beyond basic ASCII art, chafa can leverage advanced Unicode characters (like block elements and braille characters) to achieve impressive fidelity.
The tool intelligently handles image scaling, aspect ratio correction, and employs sophisticated dithering algorithms to optimize visual quality even when constrained by limited character sets or color palettes. It supports numerous image formats such as PNG, JPEG, GIF, BMP, TIFF, and WebP, and can even handle animated GIFs. chafa automatically detects terminal capabilities for optimal output but allows manual override for precise control, making it an excellent choice for displaying images in scripts, customizing terminal prompts, or simply enjoying images in a text-based environment.
CAVEATS
The visual quality of chafa's output is highly dependent on the terminal emulator, its font, and line spacing. Not all terminals fully support true color, complex Unicode characters, or advanced image protocols like Sixel or Kitty. Using large images or complex dither methods can be computationally intensive, potentially affecting performance.
INPUT FROM STANDARD INPUT
If no FILE is specified, or if FILE is given as a single hyphen (-), chafa will read image data from standard input, allowing it to be easily piped with other commands.
COMMON USE CASES
chafa is frequently used for displaying images directly within a terminal window, creating custom `motd` (Message Of The Day) files, enhancing scripts with visual output, or integrating images into terminal-based information tools like neofetch.
HISTORY
chafa is a relatively modern tool, first released around 2017-2018, developed by Hans Petter Jansson (hpj). It emerged as a more sophisticated alternative to older text-art converters, leveraging contemporary terminal capabilities such as true color and a broader range of Unicode characters. Its development has been active, focusing on high-quality output, performance, and flexibility, quickly establishing it as a popular choice for terminal image rendering.