Table of Contents

Images

WARNING: This document is for an older version of iTerm2.

iTerm2 is able to display images within the terminal. Using a similar mechanism, it can also facilitate file transfers over any transport (such as ssh or telnet), even in a non-8-bit-clean environment.

Just want to try it out and don't care about the protocol? Use the imgcat tool. Download imgcat here

Example: imgcat

Using the imgcat script, one or more images may be displayed in a terminal session. For example:

Critically, animated GIFs are supported as of version 2.9.20150512.

Retina

Starting in iTerm2 version 3.2.0, Retina displays are properly supported. Previously, they would be double-size (one display "point" per image pixel rather than one display pixel per image pixel). If you prefer the old behavior, change Prefs > Advanced > Show inline images at Retina resolution.

Protocol

iTerm2 extends the xterm protocol with a set of proprietary escape sequences. In general, the pattern is:

ESC ] 1337 ; key = value ^G

Whitespace is shown here for ease of reading: in practice, no spaces should be used.

For file transfer and inline images, the code is:

ESC ] 1337 ; File = [optional arguments] : base-64 encoded file contents ^G

The optional arguments are formatted as key=value with a semicolon between each key-value pair. They are described below:

KeyDescription of value
name  base-64 encoded filename. Defaults to "Unnamed file".
size  File size in bytes. Optional; this is only used by the progress indicator.
width  Width to render. See notes below.
height  Height to render. See notes below.
preserveAspectRatio  If set to 0, then the image's inherent aspect ratio will not be respected; otherwise, it will fill the specified width and height as much as possible without stretching. Defaults to 1.
inline  If set to 1, the file will be displayed inline. Otherwise, it will be downloaded with no visual representation in the terminal session. Defaults to 0.

The width and height are given as a number followed by a unit, or the word "auto".

  • N: N character cells.
  • Npx: N pixels.
  • N%: N percent of the session's width or height.
  • auto: The image's inherent size will be used to determine an appropriate dimension.

More on File Transfers

By omitting the inline argument (or setting its value to 0), files will be downloaded and saved in the Downloads folder instead of being displayed inline. Any kind of file may be downloaded, but only images will display inline. Any image format that macOS supports will display inline, including PDF, PICT, or any number of bitmap data formats (PNG, GIF, etc.). A new menu item titled Downloads will be added to the menu bar after a download begins, where progress can be monitored and the file can be located, opened, or removed.

Sample Code

Sample code for displaying images may be found here.

imgls

Provides an augmented directory listing that includes a thumbnail of each image in a directory.

imgcat

Displays one or more images inline at their full size.

it2dl

Downloads a file, but does not display it inline.

divider

Draws a full-width, one line-tall graphical divider.