What's the difference between OSC 0, OSC 1, and OSC 2 — why three title escapes?

OSC 0 sets BOTH the icon name AND the window title in one call (shorthand). OSC 1 sets *only* the icon name (the short label shown when the window is minimized / iconified). OSC 2 sets *only* the window title (the long string in the title bar / tab label). The split dates to X11 / ICCCM where iconified windows displayed a separate compact label. On modern terminals without iconification (Windows Terminal, macOS Terminal.app, kitty), OSC 1 is often silently no-op'd; OSC 0 and OSC 2 still work everywhere. For SSH-into-server tab labels, use OSC 2 — OSC 0 risks clobbering the icon on terminals that still honour the X11 distinction.

Why does my icon name change reset every time I open a new tab in tmux?

tmux maintains its own per-window icon name and re-emits OSC 1 to the outer terminal whenever the active window changes. Setting OSC 1 from inside an inner shell updates the *tmux window's* recorded icon name, but the moment you Ctrl-b n to the next window, tmux pushes that window's saved icon (often empty → terminal falls back to the binary name like tmux). To keep an icon across windows, set set-option -g set-titles-string '#W' and let tmux drive the title from the inner shell's automatic-rename mechanism — manual OSC 1 from one window can't persist beyond the next window switch.

OSC 1 — Set icon name (separate from window title)

Set the X11-style icon name independent of the visible window title — historically the label shown when the window is minimised.

Byte forms

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

\\x1b[\x1b]1;ICON-NAME\x07

\\033[\033]1;ICON-NAME\007

\\e[\e]1;ICON-NAME\a

ESC [ESC ] 1 ; ICON-NAME BEL

hex1b 5d 31 3b ... 07

Description

OSC 1 sets the icon name — historically the short label X11 showed for a minimised window (versus OSC 2 which set the long title visible in the title bar). OSC 0 sets both at once; OSC 1 sets only the icon name; OSC 2 sets only the title. On X11/xterm + gnome-terminal + konsole + mlterm + foot this still works as designed — the window manager picks up the icon-name attribute via XSetWMIconName. On non-X11 terminals (Windows Terminal, iTerm2, kitty, alacritty, wezterm, ghostty) there is no separate icon-name surface to render to, so most ignore OSC 1 entirely or quietly treat it as a no-op. Use OSC 0 if you want both updated together (the safe default for cross-platform tools); use OSC 1 only when you specifically need to leave the title bar untouched while updating the minimised label.

Spec citation: xterm-ctlseqs (OSC 1)

Examples

bash

printf '\033]1;build-watch\007'   # icon name only; title bar untouched

python

import sys; sys.stdout.write('\x1b]1;build-watch\x07')

fmt.Print("\x1b]1;build-watch\x07")

javascript

process.stdout.write('\x1b]1;build-watch\x07')

printf("\x1b]1;build-watch\x07");

Used in

Real-world tools that emit this sequence — anchors the bytes to commands you've already used.

xterm, urxvt, gnome-terminal, konsole, mlterm, footall the X11-native terminals honour OSC 1 — the icon-name string is published as `WM_ICON_NAME` so the window manager can show a short label (`vim`, `htop`) in the taskbar / activities switcher while the title bar keeps the full `vim — ~/proj/foo.c`
tmux `set-titles-string` + `icon-string`tmux exposes a separate `icon-string` setting alongside `titles-string` — when the outer terminal is X11-native, tmux emits OSC 1 with the short form (`#W`) for the icon and OSC 2 with the long form (`#S:#W -- #T`) for the title, mirroring the xterm convention
screen `caption` / `hardstatus`GNU screen, when run inside an xterm-family terminal, emits OSC 1 every time the focused window changes — so an Alt-Tab style switcher shows the inner window's name (`screen 0: vim`) instead of the static outer label
i3wm / sway / xmonad — minimised icon labelstiling WMs that fall back to floating layouts (i3 scratchpad, sway `move workspace`) display the icon-name when a window is minimised or moved to a non-visible workspace — emitting OSC 1 from a long job (`make all 2>&1 | tee >(grep -q ERROR && printf '\\x1b]1;BUILD FAILED\\x07')`) makes the workspace tab flash a meaningful label
non-X11 terminals (iTerm2, kitty, alacritty, wezterm, ghostty, Windows Terminal)none of them render a separate icon surface — OSC 1 is parsed and dropped (or treated as OSC 0 in some builds). Portable scripts should send OSC 0 (`\x1b]0;<name>\x07`) to update both icon and title at once unless the X11 split is explicitly required

Frequently asked

Short answers to the questions developers actually search for this sequence.

What's the difference between OSC 0, OSC 1, and OSC 2 — why three title escapes?: OSC 0 sets BOTH the icon name AND the window title in one call (shorthand). OSC 1 sets *only* the icon name (the short label shown when the window is minimized / iconified). OSC 2 sets *only* the window title (the long string in the title bar / tab label). The split dates to X11 / ICCCM where iconified windows displayed a separate compact label. On modern terminals without iconification (Windows Terminal, macOS Terminal.app, kitty), OSC 1 is often silently no-op'd; OSC 0 and OSC 2 still work everywhere. For SSH-into-server tab labels, use OSC 2 — OSC 0 risks clobbering the icon on terminals that still honour the X11 distinction.
Why does my icon name change reset every time I open a new tab in tmux?: tmux maintains its own per-window icon name and re-emits OSC 1 to the outer terminal whenever the active window changes. Setting OSC 1 from inside an inner shell updates the *tmux window's* recorded icon name, but the moment you Ctrl-b n to the next window, tmux pushes that window's saved icon (often empty → terminal falls back to the binary name like tmux). To keep an icon across windows, set set-option -g set-titles-string '#W' and let tmux drive the title from the inner shell's automatic-rename mechanism — manual OSC 1 from one window can't persist beyond the next window switch.

Common typos / look-alikes

Wrong forms developers commonly paste from Stack Overflow that look right but aren't — with the canonical correction inline.

\x1b]1;NAME\x07 to set both the window title and the icon name\x1b]0;NAME\x07 (OSC 0 sets *both*) or \x1b]2;NAME\x07 + \x1b]1;NAME\x07 (set each independently)
OSC 0 sets BOTH window and icon titles in one shot. OSC 1 sets ONLY the icon name (the short label shown on minimised X11 windows, taskbar icons, and tmux's #W). OSC 2 sets ONLY the window title (the long label shown in the title bar / browser tab equivalent). If you emit \x1b]1;myapp\x07 expecting the title bar to update, you'll see the minimised label change but the title bar stays as whatever the shell set with PROMPT_COMMAND. On Wayland / macOS where there's no separate icon-name concept, OSC 1 may be silently ignored (Apple Terminal.app, kitty under Wayland) or merged with window title (gnome-terminal).
\x1b]1;my session name (missing the BEL \x07 or ST \x1b\\ terminator)\x1b]1;my session name\x07 (BEL is the de-facto xterm terminator; \x1b\\ ST is the standards-correct one)
OSC strings are terminated by either BEL (\x07, the xterm convention since the 1980s) or ST (\x1b\\, ECMA-48 §5.2.2). Forgetting both leaves the terminal's OSC parser in string mode — subsequent stdout bytes get appended to the title string until the parser finally sees BEL or ST. Symptoms: your shell prompt vanishes for one prompt cycle (consumed as the never-finished title), or the title becomes a wall of stdout text. Apps that pipe binary data through stdout right after an OSC are especially prone — ls --color=auto | head -1; printf '\x1b]1;done\x07' reverses the order to be safe. Both terminators work on every modern terminal; ST is preferred under tmux DCS passthrough where BEL collides with tmux's own escape parsing.
embed a ; inside the icon name: \x1b]1;path: /usr/bin;ready\x07escape or replace ; inside the payload (/usr/bin / ready or /usr/bin\\;ready) — ; is the OSC parameter separator
Within an OSC, ; separates the leading numeric Ps from the payload Pt. xterm and friends use ; only for the first split (everything after the first ; is the payload), so an embedded ; is usually fine on xterm / kitty / wezterm. BUT — some terminals (Konsole, certain WT versions) re-split the payload on every ; and pass the second-and-later chunks to a different handler (e.g. expecting OSC 1;PATH;COLOR as a structured triple). The symptom: your icon name truncates at the first internal ;, or the part after the ; shows up in an unrelated field. The portable fix is to never embed raw ; in OSC payloads — use a different visual separator ( / , · , U+2014 em-dash) or backslash-escape if the consumer documents support.

Terminal support

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

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

Related sequences

In the family cookbook

OSC cookbook · 2. Window & tab titles — `OSC 0 / 1 / 2`