Provided by: timg_1.4.3-1_amd64 
NAME
timg - A terminal image and video viewer
SYNOPSIS
timg [<options> <image/video> [<image/video>...]
DESCRIPTION
Show images, play animated gifs, scroll static images or play videos in the terminal. Even show PDFs if
needed.
Useful if you want to have a quick visual check without leaving the comfort of your shell and having to
start a bulky image viewer. Sometimes this is the only way if your terminal is connected remotely via
ssh. And of course if you don’t need the resolution. While icons typically fit pixel-perfect, larger
images are scaled down to match the resolution.
The command line accepts any number of image/video filenames that it shows in sequence one per page or in
a grid in multiple columns, depending on your choice of --grid. The output is emitted in-line with mini‐
mally messing with your terminal, so you can simply go back in history using your terminals’ scroll-bar
(Or redirecting the output to a file allows you to later simply cat that file to your terminal. Even
less -R seems to be happy with such output).
The special filename “-” stands for standard input, so you can read an image from a pipe. If the input
from a pipe is a video, use the -V option (see below).
Under the hood, timg uses GraphicsMagick to open and decode a wide range of image formats. It also uses
libav to decode and play videos or images from files and URLs. With -I or -V you can choose to use only
one of these file decoders (GraphicsMagick or libav respectively).
OPTIONS
General Options
-g <width>x<height>
Output image to fit inside given geometry. By default, the size is determined by the available
space in the terminal. The image is scaled to fit inside the available box to fill the screen;
see -W if you want to fill the width.
It is possible to only partially specify the size before or after the x separator, like -g<width>x
or -gx<height>. The corresponding other value is then derived from the terminal size.
-p <[h|q|k|i]>, --pixelation=[h|q|k|i]
Choice for pixelation of the content. Value `h' chooses unicode half block characters, while `q'
chooses quarter blocks. The choice `k' chooses kitty-graphics protocol, `i' the iTerm2 graphics
protocol.
Half blocks have a pixel aspect ratio of about 1:1 and allow to represent colors correctly, but
they look more `blocky'.
Quarter blocks will have a pixel aspect ratio of 1:2 (timg will stretch the picture accordingly,
no worries), and can only represent colors approximately, as the four quadrant sub-pixels can only
be foreground or background color. This increases the spatial resolution in x-direction at ex‐
pense of slight less color accuracy. It makes it look less `blocky' and usually better.
There are terminal emulators that allow to display high-resolution pictures. If timg is detecting
to run in a Kitty, iTerm2 or WezTerm, the corresponding mode is auto-selected. You can choose the
modes explicitly with -pk (Kitty) or -pi (iTerm2 protocol, also implemented by WezTerm).
Default is `quarter' unless the terminal is graphics-capable.
--compress
For the graphics modes: this switches on compression for the transmission to the terminal. This
uses more CPU on timg, but is desirable when connected over a slow network.
-C, --center
Center image(s) and title(s) horizontally.
-W, --fit-width
Scale to fit width of the available space. This means that the height can overflow, e.g. be
longer than the terminal, so might require scrolling to see the full picture. Default behavior is
to fit within the allotted width and height.
--grid=<cols>[x<rows>]
Arrange images in a grid. If only one parameter is given, arranges in a square grid
(e.g. --grid=3 makes a 3x3 grid). Alternatively, you can choose columns and rows that should fit
on one terminal (e.g. --grid=3x2)
-w <seconds>
Wait time between images when multiple images are given on the command line. Fractional values
are allowed, so -w3.1415 would wait approximately π seconds between images.
-a Switch off anti aliasing. The images are scaled down to show on the minimal amount of pixels, so
some smoothing is applied for best visual effect. This switches off that smoothing.
-b <background-color>
Set the background color for transparent images. Common HTML/SVG/X11 color strings are supported,
such as purple, *#00ff00 or rgb(0, 0, 255).
As a `special' color, auto is allowed, which attempts to query the terminal for its background
color (Best effort; not all terminals support that). If detection fails, the fallback is `black'.
The special value none switches off blending background color.
-B <checkerboard-other-color>
Show the background of a transparent image in a checkerboard pattern with the given color, which
alternates with the -b color. Supported color specifications like in -b.
--pattern-size=<size-factor>
Scale background checkerboard pattern by this factor.
--auto-crop[=<pre-crop>]
Trim same-color pixels around the border of image before displaying. Use this if there is a bor‐
ing even-colored space aorund the image which uses too many of our available few pixels.
The optional pre-crop is number of pixels to unconditionally trim all around the original image,
for instance to remove a thin border. The link in the EXAMPLES section shows an example how this
improves showing an xkcd comic with a border.
--rotate=<exif|off>
If `exif', rotate the image according to the exif data stored in the image. With `off', no rota‐
tion is extracted or applied.
--clear
Clear screen before first image. This places the image at the top of the screen.
There is an optional parameter `every' (--clear=every), which will clean the screen before every
image. This only makes sense if there is no --grid used and if you allow some time to show the
image of course, so good in combination with -w.
-U, --upscale=[i]
Allow Upscaling. If an image is smaller than the terminal size, scale it up to fit the terminal.
By default, larger images are only scaled down and images smaller than the available pixels in the
terminal are left at the original size (this helps assess small deliberately pixelated images such
as icons in their intended appearance). This option scales up smaller images to fit available
space.
The long option allows for an optional parameter --upscale=i that forces the upscaling to be in
integer increments to keep the `blocky' appearance of an upscaled image without bilinear scale
`fuzzing'.
-V This is a video, directly read the content as video and don’t attempt to probe image decoding
first.
Usually, timg will first attempt to interpret the data as image, but if it that fails, will fall-
back to try interpret the file as video. However, if the file is coming from stdin, the first
bytes used to probe for the image have already been consumed so the fall-back would fail in that
case... Arguably, this should be dealt with automatically but isn’t :)
Long story short: if you read a video from a pipe, use -V. See link in EXAMPLES section for a an
example.
-I This is an image, don’t attempt to fall back to video decoding. Somewhat the opposite of -V.
--title=[format-string]
Print title above each image. It is possible to customize the title by giving a format string.
In this string, the following format specifiers are expanded:
• %f = full filename
• %b = basename (filename without path)
• %w = image width
• %h = image height
• %D = internal decoder used (image, video, ...)
If no format string is given, this is just the filename (%f) or, if set, what is provided in the
TIMG_DEFAULT_TITLE environment variable.
-F Behaves like –title="%f", i.e. the filename is printed as title (or, if set, the TIMG_DEFAULT_TI‐
TLE environment variable).
-f <filelist-file>
Read a list of image filenames to show from this file. The list needs to be newline separated.
This option can be supplied multiple times in which case it appends to the end of the list of im‐
ages to show. If there are also filenames on the command line, they will be shown at the very
end.
Absolute filenames in the list are used as-is, relative filenames are resolved relative to the
filelist-file itself.
-o <outfile>
Write terminal image to given filename instead of stdout.
-E Don’t hide the cursor while showing images.
--threads=<n>
Run image decoding in parallel with n threads. By default, half the reported CPU-cores are used.
--color8
Use 8 bit color mode for terminals that don’t support 24 bit color (only shows 6x6x6 = 216 dis‐
tinct colors instead of 256x256x256 = 16777216).
--version
Print version and exit.
-h, --help
Print command line option help and exit.
For Animations, Scrolling, or Video
Usually, animations are shown in full in an infinite loop. These options limit infinity.
-t<seconds>
Stop an animation after these number of seconds. Fractional values are allowed.
--loops=<num>
Number of loops through a fully cycle of an animation or video. A value of -1 stands for `forev‐
er'.
If not set, videos loop once, animated images forever unless there is more than one file to show.
If there are multiple files on the command line, animated images are only shown once if --loops is
not set to prevent the output get stuck on the first animation.
--frames=<frame-count>
Only render the first frame-count frames in an animation or video. If frame-count is set to 1,
the output behaves like a static image.
Scrolling
--scroll[=<ms>]
Scroll horizontally with an optional delay between updates (default: 60ms). In the EXAMPLES sec‐
tion is an example how to use ImageMagick to create a text that you then can scroll with timg over
the terminal.
--delta-move=<dx>:<dy>
Scroll with delta x and delta y. The default of 1:0 scrolls it horizontally, but with this option
you can scroll vertically or even diagonally.
RETURN VALUES
Exit code is
0 On reading and displaying all images successfully.
1 If any of the images could not be read or decoded or if there was no image provided.
2 If an invalid option or parameter was provided.
3 If timg could not determine the size of terminal (not a tty?). Provide -g option to provide size
of the output to be generated.
4 Could not write to output file provided with -o.
5 Could not read file list file provided with -f.
ENVIRONMENT
TIMG_DEFAULT_TITLE
The default format string used for --title. If not given, the default title format string is
"%f".
TIMG_USE_UPPER_BLOCK
If this environment variable is set to the value 1, timg will use the U+2580 - `Upper Half Block'
(▀) Unicode character.
To display pixels, timg uses a Unicode half block and sets the foreground color and background
color to get two vertical pixels. By default, it uses the U+2584 - `Lower Half Block' (▄) charac‐
ter to achieve this goal. This has been chosen as it resulted in the best image in all tested
terminals (konsole, gnome terminal and cool-retro-term). So usually, there is no need to change
that. But if the terminal or font result in a funny output, this might be worth a try. This is
an environment variable because if it turns out to yield a better result on your system, you can
set it once in your profile and forget about it.
TIMG_FONT_WIDTH_CORRECT
A floating point stretch factor in width direction to correct for fonts that don’t produce quite
square output.
If you notice that the image displayed is not quite the right aspect ratio because of the font
used, you can modify this factor to make it look correct. Increasing the visual width by 10%
would be setting it to TIMG_FONT_WIDTH_CORRECT=1.1 for instance.
This is an environment variable, so that you can set it once to best fit your terminal emulator of
choice.
TIMG_ALLOW_FRAME_SKIP
Set this environment variable to 1 if you like to allow timg to drop frames when play-back is
falling behind. This is particularly useful if you are on a very slow remote terminal connection
that can’t keep up with playing videos. Or if you have a very slow CPU.
EXAMPLES
Some example invocations including scrolling text or streaming an online video are put together at
<https://github.com/hzeller/timg#examples>
KNOWN ISSUES
This requires a terminal that can deal with Unicode characters and 24 bit color escape codes. This will
be problematic on really old installations or if you want to display images on some limited text console.
The option -V should not be necessary for streaming video from stdin; timg should internally buffer bytes
it uses for probing.
BUGS
Report bugs to <http://github.com/hzeller/timg/issues>
COPYRIGHT
Copyright (c) 2016..2021 Henner Zeller. This program is free software, provided under the GNU GPL ver‐
sion 2.0 or later <https://gnu.org/licenses/gpl.html>.
SEE ALSO
GraphicsMagick, ffmpeg(1)
AUTHORS
Henner Zeller.
Feb 2021 timg(1)