# viu

> Rust command-line image viewer for the terminal using the iTerm or Kitty graphics protocols, with a half-block fallback and animated GIF support.

Stars: 3.3k · Language: Rust · License: MIT · Categories: File Management

- Repository: https://github.com/atanunq/viu
- Page: https://www.trmn.sh/tools/viu

## Install

- Homebrew: `brew install viu`
- Pacman (Arch Linux): `pacman -S viu`
- Cargo: `cargo install viu`

## Overview

viu is a small Rust command-line application that displays images in the terminal. It is the front-end of the viuer library. It uses the iTerm or Kitty graphics protocol when the terminal supports one. Otherwise it draws the image with lower half block characters (▄). viuer picks the protocol from the value of $TERM. For half blocks it checks $COLORTERM: if the value contains truecolor or 24bit it outputs 16 million colors, and if not it falls back to ansi256.

It shows animated GIFs, reads image data from standard input (pass `-` as the file), and supports transparency. Other options include custom width and height, x/y offsets (relative to the cursor, or to the top-left corner with `--absolute-offset`), recursion into directories, and printing the file name before or after the image. With no size flags, viu fits the image to the terminal and keeps its aspect ratio. The ratio changes only when `-w` and `-h` are both given. Sixel support is experimental and sits behind the `sixel` or `icy_sixel` feature flags.

For GIFs, a single GIF file loops until Ctrl-C. When several files are passed, each GIF plays once. `--frame-rate`, `--once` and `--static` control playback. In iTerm, GIFs are handled by the terminal itself, so `--once` and `--frame-rate` have no effect there. The README notes that the Kitty protocol does not work with tmux, so `--blocks` can be used to force half-block output.

Typical users are developers and terminal users who want to preview images, for example over SSH or inside scripts, without opening a GUI viewer. Piping image data in from a tool such as curl is one example.

### Installation

```bash
# via Homebrew
brew install viu
```

```bash
# via Pacman (Arch Linux)
pacman -S viu
```

```bash
# via Cargo
cargo install viu
```

![viu running in the Kitty terminal](https://raw.githubusercontent.com/atanunq/viu/master/img/kittydemo.gif)

![viu in iTerm on a Mac](https://media.trmn.sh/cached/2a938611c1781c95c7a781ad7dfebadb17d148e1115f5f0266a12f0f2a115bbf.png)

![viu reading an image from stdin](https://media.trmn.sh/cached/a52a5844fce6429b108309d108721904a4804d639ba42a85aad7db8e1b895ec8.gif)

## Alternatives

- [ouch](https://www.trmn.sh/tools/ouch.md): CLI tool for compressing and decompressing files across 14+ formats with automatic format detection (Rust, 3.8k stars)
- [xplr](https://www.trmn.sh/tools/xplr.md): Terminal-based file explorer with Lua scripting, keyboard controls, and plugin system for command-line integration (Rust, 4.8k stars)
- [xleak](https://www.trmn.sh/tools/xleak.md): Excel file viewer and interactive TUI for terminal with multi-sheet support and export capabilities (Rust, 1.5k stars)
- [hazelnut](https://www.trmn.sh/tools/hazelnut.md): Terminal-based automated file organizer that watches folders and applies rules to move, copy, rename, or delete files based on patterns (Rust, 325 stars)
- [notox](https://www.trmn.sh/tools/notox.md): CLI tool for renaming files to remove toxic or problematic characters from filenames (Rust, 16 stars)

---

Canonical: https://www.trmn.sh/tools/viu