How to Install viu on Debian: View Images Right in Your Terminal

viu is a small, fast terminal image viewer written in Rust. It renders images, and even animated GIFs, directly inside your terminal, so you can preview a screenshot, inspect a thumbnail, or check a downloaded picture without ever leaving the shell or opening a graphical application.

On modern terminals that support graphics protocols such as Kitty’s or iTerm2’s, viu displays crisp, full-resolution images. Where those protocols are not available it falls back gracefully to Unicode half-blocks with truecolour, which still produces a surprisingly good rendering over plain SSH. That makes viu equally at home on a local desktop terminal and on a headless remote server where no image viewer exists at all.

viu is not available in the official Debian repositories, and installing it otherwise means either compiling it with Cargo or fetching release binaries by hand. The unofficial deb.griffo.io repository offers a simpler route: a prebuilt, up-to-date viu package you can install with apt.

Install the Latest viu on Debian: The Short Version

If you only came for the commands, this adds the repository and installs the latest viu .deb package on Debian:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install viu

The rest of this guide explains what each command does, how to verify the install, how to keep viu up to date, and what to check when something goes wrong.

What Makes viu Special?

  • 🖼️ Inline image rendering - Displays PNG, JPEG, WebP, BMP and more directly in the terminal
  • 🎞️ Animated GIF playback - Plays GIFs frame by frame, with control over looping and speed
  • 🚀 Written in Rust - Fast startup and a small, dependency-light static binary
  • 🐱 Reads from stdin - Pipe images straight in, ideal for scripts and one-liners
  • 📐 Flexible sizing - Fit to width, height, or exact dimensions with simple flags
  • 🌈 Graphics-protocol aware - Uses Kitty/iTerm graphics where available, Unicode blocks otherwise
  • 📁 Directory and multi-file support - View several images, or recurse through a folder
  • 🔍 Transparency handling - Preserves alpha channels when the terminal allows it

Why Use the deb.griffo.io Repository?

Installing viu from deb.griffo.io on Debian gives you:

  • Easy installation and updates through the standard APT package manager
  • Automatic dependency management handled by the packaging
  • Always tracks upstream releases so you get the latest viu
  • No compiling from source and no Rust toolchain to install
  • Works across supported Debian releases (Bookworm, Trixie and Sid)

Prerequisites

Before we begin, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, or Sid)
  • sudo privileges
  • curl installed (install with sudo apt install curl if needed)
  • A terminal with truecolour support for the best results

Step 1: Add the deb.griffo.io Repository

Add the repository GPG key and source definition:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

What these commands do:

  1. Keyrings directory: Creates /etc/apt/keyrings with the right permissions to hold the key.
  2. GPG key: Downloads and de-armours the signing key so APT can verify signatures.
  3. Repository: Adds the source line, using lsb_release -sc to detect your Debian codename.
  4. Update: Refreshes the package index so the new packages appear.

Step 2: Update the Package List

If you have not already refreshed the index, do so now:

sudo apt update

Step 3: Install viu

Install viu with one command:

sudo apt install viu

APT downloads and installs the latest packaged version of viu with any dependencies.

Step 4: Verify the Installation

Check the installed version:

viu --version

You should see output similar to:

viu 1.5.1

Getting Started with viu

viu is a single command that does one thing well: turn an image file into terminal output. The examples below cover everyday viewing, sizing, animations and piping.

View an Image

Pass one or more image paths to display them:

# A single image
viu photo.png

# Several images in sequence
viu one.png two.jpg three.webp

Add -n to print the filename above each image, which is handy when viewing many at once:

viu -n *.png

Control the Size

By default viu fits the image to the terminal width. Use flags to constrain the dimensions:

# Fit to a width of 80 columns
viu -w 80 photo.png

# Fit to a height of 40 rows
viu -h 40 photo.png

# Force exact dimensions (may distort the aspect ratio)
viu -w 100 -h 50 photo.png

Play Animated GIFs

viu plays GIFs by default, looping until you press a key. You can adjust the behaviour:

# Play the animation once, then stop
viu -1 animation.gif

# Set a custom frame rate
viu -f 15 animation.gif

# Show only the first frame, as a still image
viu -s animation.gif

Pipe Images from Other Commands

Because viu reads from standard input, it composes neatly with other tools. Use - as the filename:

# View an image fetched with curl, without saving it
curl -fsSL https://example.com/logo.png | viu -

# Preview a file selected with fzf
viu "$(ls *.png | fzf)"

Preview a Whole Directory

Point viu at a directory with -r to walk through the images it contains:

viu -r ./screenshots/

Keeping viu Updated

Because viu comes from the repository, keeping it current is part of your normal system upgrade:

sudo apt update && sudo apt upgrade

Other Tools from deb.griffo.io

The deb.griffo.io repository packages many other terminal utilities that pair well with viu:

  • Yazi - A blazing fast terminal file manager with image previews
  • Termusic - A terminal music player written in Rust
  • Fastfetch - A fast, highly customizable system information tool
  • eza - A modern, maintained replacement for ls

Troubleshooting

GPG or Key Issues

If APT reports the repository is not signed, re-add the signing key:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot find the viu package:

  1. Run sudo apt update again after adding the repository.
  2. Confirm your Debian release is supported (Bookworm, Trixie or Sid).
  3. Check the source file: cat /etc/apt/sources.list.d/deb.griffo.io.list.

Images Look Blocky or Colours Are Wrong

If output appears as coarse blocks or the colours seem off, the issue is almost always terminal capability rather than viu:

  1. Use a truecolour terminal and confirm COLORTERM is set: echo $COLORTERM should print truecolor.
  2. For crisp full-resolution output, use a terminal that implements a graphics protocol, such as Kitty or WezTerm.
  3. When rendering over tmux, note that graphics protocols are often intercepted; viu will fall back to Unicode blocks inside a multiplexer.

Uninstalling

To remove viu:

sudo apt remove viu

To also remove the repository definition and key:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Conclusion

viu is one of those small tools that quietly improves everyday terminal life. Being able to glance at an image over SSH, preview a download without a browser, or check a GIF from a script means fewer context switches and less reaching for a graphical viewer. The deb.griffo.io repository makes getting it onto Debian a single apt install, with updates that arrive through your usual upgrades.

Whether you live in a Kitty window on the desktop or spend your day on headless servers, viu turns the terminal into a perfectly capable image viewer. Combine it with a file manager or a fuzzy finder and previewing images never has to leave the keyboard again.

Frequently Asked Questions

How do I install the latest viu on Debian?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install viu. The repository tracks upstream viu releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for viu?

Yes. deb.griffo.io publishes viu as a signed .deb for Debian. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update viu to the latest version?

Run sudo apt update && sudo apt upgrade. Once viu is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

How do I install viu on Ubuntu?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Ubuntu specifics: How to install viu on Ubuntu.

Which Debian releases are supported?

Bookworm 12, Trixie 13 and Sid. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream viu project.