timg

timg [OPTIONS] FILE...

-s, --size
    Specifies the output dimensions for the image in columns and rows (e.g., 80x24).

-w, --width
    Sets the maximum output width in terminal columns.

-h, --height
    Sets the maximum output height in terminal rows.

-a, --auto
    Automatically adjusts the image size to fit the current terminal window.

-f, --format
    Selects the rendering method. Common methods include auto, 24bit, sixel, kitty, block, ascii.

-l, --loop
    For animated GIFs, specifies the number of times to loop (0 for infinite looping).

-d, --delay
    Sets the delay in milliseconds between frames of an animation.

-b, --background
    Sets the background color for padding or transparent areas (e.g., red, #RRGGBB).

--upscale
    Enables upscaling of small images to fill the designated display area.


    One or more paths to image files (e.g., image.jpg, my_gif.gif) to be displayed.

timg (Terminal IMaGe viewer) is a versatile command-line utility designed to display images directly within your terminal emulator. It supports a wide array of image formats, including JPEG, PNG, GIF, and even some video formats by rendering frames. timg can utilize various display methods, adapting to your terminal's capabilities, from simple character-based ASCII art to advanced true color block characters,
or even direct pixel rendering via sixel graphics (supported by terminals like mlterm, xterm with sixel patches) and the Kitty graphics protocol.

It's an invaluable tool for quick image previews without launching a separate GUI application, integrating visual content into terminal-centric workflows, or scripting automated image processing tasks where visual feedback is needed. Beyond static images, timg also excels at displaying animated GIFs and videos by sequentially rendering their frames, offering options to control looping and frame delay.

Terminal Compatibility: Not all terminal emulators support every rendering method (e.g., sixel or Kitty graphics protocol are specific). The visual quality and available features highly depend on your terminal's capabilities.
Performance: Displaying very large images or complex animated GIFs can be resource-intensive, potentially leading to slower rendering or higher CPU usage, especially with character-based methods.
Aspect Ratio Distortion: When using character-based rendering, the image aspect ratio might appear distorted due to the non-square nature of terminal character cells. Using --font-width and --font-height can help.
Color Accuracy: While timg supports true 24-bit color, its effective display depends on terminal support; otherwise, colors might be dithered or approximated.

timg offers various rendering methods via the --format option:
auto: (Default) Automatically chooses the best available method for your terminal.
24bit: Uses 24-bit ANSI true colors and Unicode block characters to render images with high fidelity.
sixel: Renders images using the DEC sixel graphics protocol, providing near-pixel-perfect output on compatible terminals (e.g., xterm with sixel, mlterm).
kitty: Utilizes the Kitty graphics protocol, offering high-resolution image display specifically for the Kitty terminal emulator.
block: Renders using standard block characters (e.g., half-block Unicode characters) and 256-color or 24-bit ANSI colors.
ascii: Converts the image into ASCII art, using character density to represent image brightness and contrast.

timg is ideal for integration into shell scripts. For example, you can use it to preview images downloaded on the fly, display QR codes, or visualize output from other command-line tools that generate image data. Its ability to automatically resize and select the best format makes it robust for diverse scripting environments.

timg emerged as a modern solution to address the growing demand for displaying graphical content directly within the terminal, improving upon earlier, often more specialized, ASCII art converters. Its development focuses on leveraging advancements in terminal emulators, such as true color support (24-bit ANSI escape sequences), the re-emergence of sixel graphics, and newer protocols like the Kitty graphics protocol.

While not having a long historical lineage like some core Unix utilities, timg represents a contemporary effort to enhance the terminal experience, integrating robust image processing capabilities (often via libraries like ImageMagick or FreeImage) with flexible terminal rendering techniques. It aims to provide a unified, powerful tool for what was previously achieved by a collection of smaller, less capable utilities.

chafa(1), jp2a(1), caca(1), img2txt(1), convert(1)