Skip to content
<awesome-gh-repos>
vic

atanunq/viu

Terminal image viewer with native support for iTerm and Kitty
Source code at GitHub https://github.com/atanunq/viu
atanunq/viu.json
{
  "createdAt": "2019-04-12T14:51:16Z",
  "defaultBranch": "master",
  "description": "Terminal image viewer with native support for iTerm and Kitty",
  "fullName": "atanunq/viu",
  "homepage": "",
  "language": "Rust",
  "name": "viu",
  "pushedAt": "2024-12-04T18:31:08Z",
  "stargazersCount": 2964,
  "topics": [
    "cli",
    "image-viewer",
    "rust",
    "terminal"
  ],
  "updatedAt": "2025-11-25T09:55:11Z",
  "url": "https://github.com/atanunq/viu"
}

Description

Section titled “Description”

A small command-line application to view images from the terminal written in Rust. It is basically the front-end of viuer. It uses either iTerm or Kitty graphics protocol, if supported. If not, lower half blocks (▄ or \u2584) are displayed instead.

Based on the value of $TERM, viuer decides which protocol to use. For half blocks, $COLORTERM is inspected. If it contains either truecolor or 24bit, truecolor (16 million colors) will be used. If not, it will fallback to using only ansi256. A nice explanation can be found in this gist.

Features

Section titled “Features”
  • Native iTerm and Kitty support
  • Animated GIF support
  • Accept media through stdin
  • Custom dimensions
  • Transparency
  • Experimental Sixel support (behind the sixel feature flag)

Installation

Section titled “Installation”
Section titled “From source (recommended)”

Installation from source requires a local Rust environment.

Terminal window
git clone https://github.com/atanunq/viu.git


# Build & Install
cd viu/
cargo install --path .


# Use
viu img/giphy.gif

Or without cloning:

Terminal window
cargo install viu

Binary

Section titled “Binary”

A precompiled binary can be downloaded from the release page. GPG fingerprint is B195BADA40BEF20E4907A5AC628280A0217A7B0F.

Packages

Section titled “Packages”

MacOS

Section titled “MacOS”

Available in brew.

Terminal window
brew install viu

Arch Linux

Section titled “Arch Linux”

Available in extra/viu.

Terminal window
pacman -S viu

NetBSD

Section titled “NetBSD”

Available in graphics/viu.

Usage

Section titled “Usage”

Examples

Section titled “Examples”

On a Kitty terminal:

![Kitty]!(img/kittydemo.gif)

On a Mac with iTerm:

![iTerm]!(img/iterm.png)

Using half blocks (Kitty protocol and tmux do not get along):

![Demo]!(img/demo.gif)

![Demo]!(img/gifdemo.gif)

![Demo]!(img/curldemo.gif)

Ctrl-C was pressed to stop the GIFs.

When viu receives only one file and it is GIF, it will be displayed over and over until Ctrl-C is pressed. However, when couple of files are up for display the GIF will be displayed only once.

iTerm note

Section titled “iTerm note”

iTerm can handle GIFs by itself with better performance, but configuration through --once and --frame-rate will have no effect there.

Aspect Ratio

Section titled “Aspect Ratio”

If no flags are supplied to viu it will try to get the size of the terminal where it was invoked. If it succeeds it will fit the image and preserve the aspect ratio. The aspect ratio will be changed only if both options -w and -h are used together.

Command line options

Section titled “Command line options”
View images right from the terminal.


Usage: viu [OPTIONS] [file]...


Arguments:
  [file]...  The images to be displayed. Set to - for standard input.


Options:
  -w, --width <width>
          Resize the image to a provided width
  -h, --height <height>
          Resize the image to a provided height
  -x <x>
          X offset [default: 0]
  -y <y>
          Y offset [default: 0]
  -a, --absolute-offset
          Make the x and y offset be relative to the top left terminal corner. If not set, they are relative to the cursor's position.
  -r, --recursive
          Recurse down directories if passed one
  -b, --blocks
          Force block output
  -n, --name
          Output the name of the file before displaying
  -t, --transparent
          Display transparent images with transparent background
  -f, --frame-rate <frames-per-second>
          Play the gif at a given frame rate
  -1, --once
          Loop only once through the gif
  -s, --static
          Show only the first frame of the gif
  -H, --help
          Print help information
  -V, --version
          Print version information