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 [OPTIONS] [FILE...]

-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.

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.

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.

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.

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.

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.

jp2a(1), img2txt(1), catimg(1), timg(1)