pixterm

Render a static image directly in the terminal

$ pixterm [path/to/file]

$ pixterm -s 2 [path/to/file]

$ pixterm -tr [24] -tc [80] [path/to/file]

$ pixterm -m [000000] -d 2 [path/to/file]

pixterm [OPTIONS] <IMAGE_PATH>

-c, --columns <int>
    Specifies the target width of the image in character columns.

-r, --rows <int>
    Specifies the target height of the image in character rows.

-s, --scale <float>
    Applies a scaling factor to the image. A value of 1.0 means no scaling. Can be used instead of or in conjunction with --columns and --rows.

-t, --type <string>
    Defines the output rendering type. Common values include ascii, block, braille, iterm, kitty, and sixel. The default usually attempts auto-detection or falls back to a suitable method.

-j, --jpeg-quality <int>
    Sets the JPEG compression quality (0-100) when rendering images using methods that involve JPEG encoding (e.g., some inline protocols). Higher values mean better quality but larger data.

-w, --watch
    Monitors the input image file for changes and automatically re-renders the image in the terminal when modifications are detected. Useful for dynamic content or development.

-h, --help
    Displays a help message with usage information and available options.

-v, --version
    Shows the version information of the pixterm utility.

pixterm is a versatile command-line tool written in Go that empowers users to render images directly within their terminal emulator. Unlike traditional image viewers that open a separate window, pixterm integrates graphical content seamlessly into the command-line environment. It achieves this by leveraging advanced terminal capabilities, including the iTerm2 inline image protocol, Kitty graphics protocol, and Sixel graphics, to display various image formats like PNG, JPEG, GIF, and BMP. This functionality is invaluable for developers, system administrators, and anyone working in a terminal, allowing for quick previews of images, embedding graphics in script outputs, or visualizing data without breaking the workflow. For terminals lacking these modern features, pixterm intelligently falls back to rendering images as less detailed but broadly compatible ASCII art, block characters, or braille patterns, ensuring a visual representation is always available.

Terminal Compatibility: pixterm's advanced rendering capabilities (e.g., iTerm2, Kitty, Sixel) require a compatible terminal emulator. If your terminal does not support a specific protocol, the image may not display correctly or may fall back to less detailed ASCII/block rendering.
Performance: Displaying very large images or continuously watching files with the --watch option can consume significant terminal resources or cause visual flickering, depending on your system and terminal emulator.
Installation: pixterm is not a standard system utility and typically needs to be installed by compiling from source or using Go's package manager (go install).

pixterm supports a wide range of common image formats, including PNG, JPEG, GIF, BMP, and WebP. The underlying Go image processing libraries ensure broad compatibility.

When no specific dimensions (--columns, --rows) or scaling factor (--scale) are provided, pixterm attempts to automatically scale the image to fit within the current terminal window dimensions, preserving the aspect ratio.

pixterm was created by Dalton Pereira as a modern command-line utility written in Go. Its development aimed to provide a user-friendly and efficient way to display graphical images directly within the terminal, leveraging the capabilities of modern terminal emulators while also offering broader compatibility through ASCII and block character rendering. It addresses the growing need for richer media display within command-line environments.

chafa(1), jp2a(1), lsix(1), feh(1)