OSC 1337 — iTerm2 inline images & file transfer

Embed images, files, or proprietary iTerm2 state into the terminal stream — the predecessor protocol that Kitty / Sixel later largely supplanted.

Byte forms

Every common string-literal form so you can paste-and-search either direction.

\\x1b[\x1b]1337;File=name=<base64>;size=<bytes>;inline=1:<base64-data>\x07

\\033[\033]1337;File=...:<base64>\007

\\e[\e]1337;File=...:<base64>\a

ESC [ESC ] 1337 ; <key=value;...> : <base64> BEL

hex1b 5d 31 33 33 37 3b ... 07

Description

iTerm2's proprietary OSC 1337 multiplexes a whole family of out-of-band features onto a single OSC code, distinguished by the first body token. The most-used form is File=...:<base64> for inline images and file transfers — same vocabulary, different inline= flag. Keys (key=value, ;-separated, before the :):

- name=<base64-of-filename> — display name / save-target on Cmd-S. - size=<bytes> — for progress bar. - inline=1 — render as an image right at the cursor (default 0 means 'download to ~/Downloads'). - width=<n> / height=<n> — sizing in cells, pixels (px suffix), percent (% suffix), or auto. - preserveAspectRatio=0|1 — default 1. - type=<mime> — image/png, image/jpeg, image/gif (animated), application/pdf etc.

After the keys, a single : separator, then the base64-encoded payload. Animation frames in GIF replay naturally. iTerm2 also defines non-File OSC 1337 sub-codes for RemoteHost=<user>@<host>, CurrentDir=<path> (mostly subsumed by OSC 7 now), SetUserVar=<name>=<base64> (for custom status-bar variables), SetMark (jump points distinct from OSC 133), ReportCellSize (replies with pixel size of one cell — Tmux uses this for ratatui-style pixel-accurate Sixel sizing). Modern adoption: iTerm2 (origin); WezTerm + Konsole 22.04+ implement the File= subset; Kitty / Ghostty advertise their *own* protocols (kitty graphics / WezTerm imgcat-compat) but accept OSC 1337 File= for the imgcat shell-script compatibility shim distributed by iTerm2. Use case today: shipping an image into the terminal pane without depending on Sixel; the imgcat script is the canonical entry-point.

Spec citation: iTerm2 Proprietary Escape Codes (OSC 1337)

Parameters

File=...:<base64>	Inline image / file transfer subprotocol. Keys precede the `:`; base64 payload follows. Use `inline=1` to render at cursor, 0 to download.
SetUserVar / SetMark / RemoteHost / CurrentDir / ReportCellSize	Non-File subcodes for status-bar variables, navigation marks, shell-integration host/cwd advertising, and cell-pixel-size queries.

Examples

bash

# imgcat-style: render PNG at cursor.\nB64=$(base64 -w 0 ./logo.png)\nprintf '\033]1337;File=name=%s;inline=1:%s\007' "$(printf 'logo.png' | base64 -w 0)" "$B64"

python

import base64, sys\ndata = open('logo.png','rb').read()\nname = base64.b64encode(b'logo.png').decode()\npayload = base64.b64encode(data).decode()\nsys.stdout.write(f'\x1b]1337;File=name={name};inline=1:{payload}\x07')

// Advertise CWD via iTerm2's older mechanism (most apps prefer OSC 7 now):\nfmt.Print("\x1b]1337;CurrentDir=/Users/me/code\x07")

javascript

// Set a custom iTerm2 user var that a status-bar component can read:\nconst b64 = Buffer.from('on-call').toString('base64')\nprocess.stdout.write(`\x1b]1337;SetUserVar=role=${b64}\x07`)

/* Probe iTerm2/wezterm cell-pixel size — used by Sixel renderers: */\nfputs("\x1b]1337;ReportCellSize\x07", stdout);\n/* Reply lands on stdin as another OSC 1337. */

Terminal support

xterm: no
Linux console (fbcon): no
macOS Terminal.app: no
iTerm2: yes
Windows Terminal: no
cmd.exe / ConPTY: no
kitty: partial
alacritty: no
WezTerm: yes
Ghostty: partial
GNOME Terminal: no
Konsole: yes
tmux: no
GNU screen: no

xterm	Linux console (fbcon)	macOS Terminal.app	iTerm2	Windows Terminal	cmd.exe / ConPTY	kitty	alacritty	WezTerm	Ghostty	GNOME Terminal	Konsole	tmux	GNU screen
no	no	no	yes	no	no	partial	no	yes	partial	no	yes	no	no

Related sequences

In the family cookbook

OSC cookbook · 6. Inline images & progress — `OSC 1337` and `OSC 9 ; 4`