GeneralOptions
Most likely commonly needed options first.
-p<[h|q|s|k|i]>, --pixelation=[h|q|s|k|i]
Choice for pixelation of the content.
Available values
half (short `h')
Uses unicode half block characters, this is the lowest resolution. Color is using a lower
or upper half block and chooses the foreground color and background color to make up two
vertical pixels per character cell. Half blocks have a pixel aspect ratio of about 1:1 and
represent colors correctly, but they look more `blocky'.
quarter (short `q')
This chooses a Unicdoe character with small sub-blocks for four pixels per characcter cell.
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 expense of slight less color accuracy. It makes it look less
`blocky' and usually better.
sixel (short `s')
Sixel output allows a high resolution image output that dates back to DEC VT200 and VT340
terminals. This image mode provides full resolution on a 256 color palette that timg
optimizes for each image. You find the sixel protocol implemented by xterm (invoke with
-ti vt340) and mlterm or konsole. Recently, more terminal emulators re-discovered this
format and started implementing it. This does not work in tmux, but there is a tmux fork
with sixel support around.
kitty (short `k')
The Kitty terminal implements an image protocol that allows for full 24Bit RGB/32 Bit RGBA
images to be displayed. This is implemented in the kitty terminal but also e.g. konsole.
You can even use this in tmux: This is the only protocol that can work around the
reluctance of tmux to allow graphics protocols. Some creative workarounds (Unicode
placeholders) are used that are only implemented in kitty version >= 0.28 right now. Also
needs tmux version >= 3.3. You have to explicitly set the -pk option inside tmux as timg
would otherwise just use block-pixels there.
iterm2 (short `i')
The iterm2 graphics is another image protocol that allows for full 24 Bit RGB/32 Bit RGBA
images. It originated on the popular macOS OpenSource iTerm2 terminal but is now also
implemented by wezterm and konsole as well as in the VSCode-terminal (enable in vscode
settings at checkbox `Terminal > Integrated: Enable images').
If no option is given, default is taken from environment variable TIMG_PIXELATION. If that is not
set, timg attempts to auto-detect the available terminal feature. Not all full-resolution
compatible terminals can be auto-detected so it will fall back to quarter in that case. Consider
passing the -p option or set the TIMG_PIXELATION environment variable in that case.
--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). This is a very useful option if you want to browse images (see
examples below).
-C, --center
Center image(s) and title(s) horizontally in their alotted space.
--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, qoi, sta, openslide, ...)
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 <filelist-file>
Read a list of image filenames to show from this file. The list needs to be newline separated, so
one filename per line. This option can be supplied multiple times in which case it appends to the
end of the list of images to show. If there are also filenames on the command line, they will
also be shown after the images from the file list have been shown.
Absolute filenames in the list are used as-is, relative filenames are resolved relative to the
currentdirectory.
(Note: this behavior changed between v1.5.0 and v1.5.1: previously, -f was resolving relative to
the filelist; this changed to current directory. Look-up relative to the file list is provided
with with uppercase -F).
-F <filelist-file>
Like -f, but relative filenames are resolved relative to the directorythefilelistresidesin.
This allows you to e.g. have a file list at the top of a directory hierarchy with relative
filenames but are not required to change into that directory first for timg to resolve the
relative paths.
-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).
The special value none switches off blending background color and relies on the terminal to
provide alpha-blending. This works well with kitty and iterm2 graphics, but might result in less
blended edges for the text-block based pixelations.
Another special value is auto:
• For graphics modes, this behaves like none, sending RGBA images for alpha-blending directly in
the terminal.
• For text-block modes, this attempts to query the terminal for its background color (Best effort;
not all terminals support that). If detection fails, the fallback is `black'.
Default is auto.
-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. The allows for HTTML/SVG/X11 colors like -b.
The checkerboard pattern has square blocks one character cell wide and half a cell high (see
--pattern-size to change).
A common combination would be to use -bgray -Bdarkgray for backgrounds known from image editors.
Sometimes setting such background is the only way to see an image, e.g. if you have an image with
a transparent background showing content with the same color as your terminal background...
--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
boring 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
rotation is extracted or applied.
-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.
-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 (e.g. icons).
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'.
--clear[=every]
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.
-V Tell timg that 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.
-w<seconds>
Wait time in seconds between images when multiple images are given on the command line.
Fractional values such as -w0.3 are allowed.
-wr<seconds>
Similar to -w, but wait time between rows. If a --grid is chosen, this will wait at the end of a
completed row. If no grid is chosen, then this is equivalent to -w. Both, -w and -wr can be
provided to show each image individually, but also have a wait time between rows.
-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 option switches off that smoothing.
-g<width>x<height>
Geometry. Scale output to fit inside given number of character cells. By default, the size is
determined by the available space in the terminal, so you typically won’t have to change this.
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.
-o <outfile>
Write terminal image to given filename instead of stdout.
-E Don’t hide the cursor while showing images.
--compress[=<level>]
For the kitty and iterm2 graphics modes: this chooses the compression for the transmission to the
terminal. This uses more CPU on timg, but is desirable when connected over a slow network.
Default compression level is 1 which should be reasonable default in almost all cases. To
disable, set to 0 (zero). Use --verbose to see the amount of data timg sent to the terminal.
--threads=<n>
Run image decoding in parallel with n threads. By default, up to 3/4 of the reported CPU-cores
are used.
--color8
For half and quarter block pixelation: Use 8 bit color mode for terminals that don’t support 24
bit color (only shows 6x6x6 = 216 distinct colors instead of 256x256x256 = 16777216).
--version
Print version and exit.
--verbose
Print some useful information such as observed terminal cells, chosen pixelation, or observed
frame-rate.
-h Print command line option help and exit.
--help Page through detailed manpage-like help and exit.
--debug-no-frame-delay
Don’t delay frames in videos or animations but emit as fast as possible. This might be useful for
developers of terminal emulations to do performace tests or simply if you want to redirect the
output to a file and don’t want to wait.
ForAnimations,Scrolling,orVideo
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
`forever'.
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 just is the first frame so behaves like a static image. Typically you’d use it when
you show a bunch of images to quickly browse without waiting for animations to finish.
--frame-offset=<offset>
For animations or videos, start at this frame.
Scrolling--scroll[=<ms>]
Scroll horizontally with an optional delay between updates (default: 60ms). In the EXAMPLES
section 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.
Install Now
PNG Icons
