viu

Render an image or animated GIF

$ viu [path/to/file]

$ curl [[-s|--silent]] [https://example.com/image.png] | viu -

$ viu [[-t|--transparent]] [path/to/file]

$ viu [[-w|--width]] [width] [[-h|--height]] [height] [path/to/file]

$ viu [[-n|--name]] [path/to/file]

viu [options] <image_file(s)>

-w <width>, --width <width>
    Sets the maximum width of the output image in characters.

-h <height>, --height <height>
    Sets the maximum height of the output image in lines.

-s, --stretch
    Stretches the image to fill the available width/height of the terminal, potentially ignoring the aspect ratio.

-t, --truecolor
    Forces 24-bit true color output, providing better color fidelity if supported by the terminal. Overrides block character mode.

-b, --blocks
    Forces rendering using Unicode block characters. This is generally more compatible across terminals but offers less detail than true color.

-c <contrast>, --contrast <contrast>
    Adjusts the output contrast. Use a float value (e.g., 1.5 for increased contrast, 0.5 for decreased).

--transparent
    Renders transparent images with proper transparency, blending with the terminal background.

--upscale
    Allows small images to be upscaled to fit the specified dimensions or terminal size, rather than only downscaling.

-v, --version
    Prints the viu version information and exits.

--help
    Displays a help message and exits.

viu is a lightweight, command-line image viewer that renders images directly within the terminal emulator using Unicode block characters and true-color support. Written in Rust, it leverages modern terminal capabilities to provide a surprisingly clear representation of images without needing a graphical display server.

It's particularly useful for quick image previews on remote servers, headless environments, or for integrating image display into shell scripts. viu supports various common image formats and can automatically scale images to fit the terminal window, making it a versatile tool for developers, system administrators, and anyone who needs to interact with images purely from the command line. Its focus is on speed and simplicity, providing a no-frills way to visualize images within a text-based interface.

Performance can be limited by terminal capabilities and network speed (e.g., SSH). Rendering quality is highly dependent on your terminal emulator's support for true colors and Unicode characters. viu is designed for display, not interactive manipulation, so it lacks features like zooming, panning, or editing.

While it attempts to preserve aspect ratio by default, using --stretch or specific width/height values may distort the image.

viu offers different rendering modes: true color for high fidelity (requiring a compatible terminal) and block character mode for broader compatibility and a more 'pixelated' appearance. You can explicitly choose between them using the -t and -b options; -b takes precedence if both are specified.

Beyond simple image viewing, viu is invaluable for scripting image processing workflows, quick previews of generated graphics in CI/CD pipelines, or inspecting datasets on remote machines without needing to transfer files or set up X forwarding. It seamlessly integrates into shell scripts for automated image verification or display.

viu emerged from the growing need to visualize images directly within command-line environments, especially prevalent in server management and scripting where a graphical desktop might be absent. Developed in Rust, it benefits from the language's performance characteristics and cross-platform compatibility. It represents a modern approach to terminal image rendering, moving beyond ASCII art to leverage true color and Unicode block elements. Its development reflects a broader trend in the Linux community to enhance the capabilities of the terminal, making it a more versatile and visually rich environment.

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