viu

A command-line tool to view images in the terminal, with support for the Kitty graphics protocol, iTerm2 inline images, and Sixel.

cli

⎔ Repository 📦 crates.io

viu is a small command-line tool for displaying images directly in the terminal. It supports multiple rendering backends — the Kitty graphics protocol, iTerm2 inline images, and Sixel — and falls back to Unicode half-block characters when none are available, making it work in virtually any terminal emulator.

Features

Multiple backends — uses the best available protocol for your terminal: Kitty, iTerm2, Sixel, or Unicode block characters
Wide format support — displays PNG, JPEG, GIF (with animation), BMP, ICO, TIFF, WebP, and more via the image crate
Animated GIFs — plays animated GIFs in the terminal at the correct frame rate
Resize control — scale images to a specified width/height in terminal cells, or let viu fit them automatically
Stdin support — pipe image data directly into viu without writing to disk
Directory browsing — pass a directory to display all images inside it in sequence

Installation

cargo install viu

Or via your package manager:

# macOS
brew install viu

# Arch Linux
pacman -S viu

# Nix
nix-env -iA nixpkgs.viu

# Debian / Fedora
# No official apt/dnf package available.
# Download a pre-built binary from the releases page:
# https://github.com/atanunq/viu/releases

Usage

# Display an image
viu photo.jpg

# Display a PNG
viu screenshot.png

# Display all images in a directory
viu ~/Pictures/

# Resize to a specific width (in terminal columns)
viu -w 60 photo.jpg

# Resize to a specific height (in terminal rows)
viu -h 20 photo.jpg

# Read from stdin (e.g. download and display without saving)
curl -sL https://example.com/image.jpg | viu -

# Display an animated GIF
viu animation.gif

# Force a specific backend
viu --blocks photo.jpg    # Unicode block characters only

Terminal compatibility

Terminal	Best backend
Kitty	Kitty graphics protocol (full quality)
WezTerm	Kitty graphics protocol
iTerm2	iTerm2 inline images
foot	Sixel
xterm	Sixel
Everything else	Unicode half-blocks

For the highest quality output, use viu inside Kitty or WezTerm — both support the Kitty graphics protocol, which renders images at full pixel resolution rather than approximating them with coloured characters.

Tips

Pair with fzf or skim for an interactive image picker:

ls *.jpg | fzf --preview 'viu -w 80 -h 24 {}'

Use inside Yazi as a preview handler for image files
Pipe from curl to quickly preview remote images without saving them