Skip to main content
ansicode

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 / ReportCellSizeNon-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')
go
// 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`)
c
/* 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

Related sequences

In the family cookbook

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