# icat - Display images in the terminal¶

The icat kitten can be used to display arbitrary images in the kitty terminal. Using it is as simple as:

kitty +kitten icat image.jpeg


It supports all image types supported by ImageMagick. It even works over SSH. For details, see the kitty graphics protocol.

You might want to create an alias in your shell’s configuration files:

alias icat="kitty +kitten icat"


Then you can simply use icat image.png to view images.

Note

ImageMagick must be installed for icat to work.

The icat kitten has various command line arguments to allow it to be used from inside other programs to display images. In particular, --place, --detect-support and --print-window-size.

## Command Line Interface¶

kitty +kitten icat [options] image-file ...


A cat like utility to display images in the terminal. You can specify multiple image files and/or directories. Directories are scanned recursively for image files. If STDIN is not a terminal, image data will be read from it as well.

### Options¶

--align <ALIGN>

Horizontal alignment for the displayed image. Default: center Choices: center, left, right

--place <PLACE>

Choose where on the screen to display the image. The image will be scaled to fit into the specified rectangle. The syntax for specifying rectangles is <width>x<height>@<left>x<top>. All measurements are in cells (i.e. cursor positions) with the origin (0, 0) at the top-left corner of the screen.

--scale-up

When used in combination with --place it will cause images that are smaller than the specified area to be scaled up to use as much of the specified area as possible.

--clear

Remove all images currently displayed on the screen.

--transfer-mode <TRANSFER_MODE>

Which mechanism to use to transfer images to the terminal. The default is to auto-detect. file means to use a temporary file and stream means to send the data via terminal escape codes. Note that if you use the file transfer mode and you are connecting over a remote session then image display will not work. Default: detect Choices: detect, file, stream

--detect-support

Detect support for image display in the terminal. If not supported, will exit with exit code 1, otherwise will exit with code 0 and print the supported transfer mode to stderr, which can be used with the --transfer-mode option.

--detection-timeout <DETECTION_TIMEOUT>

The amount of time (in seconds) to wait for a response form the terminal, when detecting image display support. Default: 10

--print-window-size

Print out the window size as widthxheight (in pixels) and quit. This is a convenience method to query the window size if using kitty icat from a scripting language that cannot make termios calls.