Please note that this is a "living document" and may lag or lead the state of the current stable release in a number of areas--as you might imagine, precisely documenting escape codes and their behaviors and cross-checking with the various technical documents is laborious and tedious and I only have so much spare time!

If you notice that something is inaccurate or missing, please do file an issue so that it can be resolved!

Output/Escape Sequences

WezTerm considers the output from the terminal to be a UTF-8 encoded stream of codepoints. No other encoding is supported. As described below, some C1 control codes have both 7-bit ASCII compatible as well as 8-bit representations. As ASCII is a compatible subset of UTF-8, the 7-bit representations are preferred and processed without any special consideration.

The 8-bit values are recognized, but only if the 8-bit value is treated as a unicode code point and encoded via a UTF-8 multi-byte sequence.

Printable Codepoints

Codepoints with value 0x20 and higher are considered to be printable and are applied to the terminal display using the following rules:

  • Codepoints are buffered until a C0, C1 or other escape/control sequence is encountered, which triggers a flush and processing continues with the next step.
  • The buffered codepoint sequence is split into unicode graphemes, which means that combining sequences and emoji are decoded. Processing continues for below for each individually recognized grapheme.
  • If DEC line drawing mode is active, graphemes j-n, q, t-x are translated to equivalent line drawing graphemes and processing continues.
  • If prior output/actions require it, the cursor position may be moved to a new line and the terminal display may be scrolled to make accomodate it.
  • An appropriate number of cells, starting at the current cursor position, are allocated based on the column width of the current grapheme and are assigned to the grapheme. The current current graphics rendition state (such as colors and other presentation attributes) is also applied to those cells. If insert mode is active, those cells will be inserted at the current cursor position, otherwise they will overwrite cells at the current cursor position.
  • The cursor position will be updated based on the column width of the grapheme.

After the graphemes are applied to the terminal display, the rendering portion of WezTerm will attempt to apply your font shaping configuration based on runs of graphemes with matching graphic attributes to determine which glyphs should be rendered from your fonts; it is at this stage that emoji and ligatures are resolved.

C0 Control Codes

Codepoints in the range 0x00-0x1F are considered to be C0 control codes. C0 controls will flush any buffered printable codepoints before triggering the action described below.

SeqHexNameDescriptionAction
^@0x00NULNullIgnored
^A0x01SOHStart of HeadingIgnored
^B0x02STXStart of TextIgnored
^C0x03ETXEnd of TextIgnored
^D0x04EOTEnd of TransmissionIgnored
^E0x05ENQEnquiryIgnored
^F0x06ACKAcknowledgeIgnored
^G0x07BELBellLogs Ding! (this is the bell) to stderr of the WezTerm process. See #3
^H0x08BSBackspaceMove cursor left by 1, constrained by the left margin. If Reverse Wraparound and dec auto wrap modes are enabled, moving left of the left margin will jump the cursor to the right margin, jumping to bottom right margin if it was at the top left.
^I0x09HTHorizontal TabMove cursor right to the next tab stop
^J0x0ALFLine FeedIf cursor is at the bottom margin, scroll the region up, otherwise move cursor down 1 row
^K0x0BVTVertical TabTreated as Line Feed
^L0x0CFFForm FeedTreated as Line Feed
^M0x0DCRCarriage ReturnIf cursor is left of leftmost margin, move to column 0. Otherwise move to left margin
^N0x0ESOShift OutIgnored
^O0x0FSIShift InIgnored
^P0x10DLEData Link EscapeIgnored
^Q0x11DC1Device Control OneIgnored
^R0x12DC2Device Control TwoIgnored
^S0x13DC3Device Control ThreeIgnored
^T0x14DC4Device Control FourIgnored
^U0x15NAKNegative AcknowledgeIgnored
^V0x16SYNSynchronous IdleIgnored
^W0x17ETBEnd Transmission BlockIgnored
^X0x18CANCancelIgnored
^Y0x19EMEnd of MediumIgnored
^Z0x1ASUBSubstituteIgnored
^[0x1BESCEscapeIntroduces various escape sequences described below
^\0x1CFSFile SeparatorIgnored
^]0x1DGSGroup SeparatorIgnored
^^0x1ERSRecord SeparatorIgnored
^_0x1FUSUnit SeparatorIgnored

C1 Control Codes

As mentioned above, WezTerm only supports UTF-8 encoding. C1 control codes have an 8-bit representation as well as a multi-codepoint 7-bit escape sequence.

The 8-bit representation is recognized if the 8-bit value is treated as a unicode code point and encoded as a multi-byte UTF-8 sequence. Sending the 8-bit binary value will not be recognized as intended, as those bitsequences are passing through a UTF-8 decoder.

The table below lists the 7-bit C1 sequence (which is preferred) as well as the codepoint value, along with the corresponding meaning.

As with C0 control codes, C1 controls will flush any buffered printable codepoints before triggering the action described below.

SeqCodepointNameDescriptionAction
ESC D0x84INDIndexMoves the cursor down one line in the same column. If the cursor is at the bottom margin, the page scrolls up
ESC E0x85NELNext LineMoves the cursor to the left margin on the next line. If the cursor is at the bottom margin, scroll the page up
ESC H0x88HTSHorizontal Tab SetSets a horizontal tab stop at the column where the cursor is
ESC M0x8DRIReverse IndexMove the cursor up one line. If the cursor is at the top margin, scroll the region down
ESC P0x90DCSDevice Control StringDiscussed below
ESC [0x9BCSIControl Sequence IntroducerDiscussed below
ESC \0x9CSTString TerminatorNo direct effect; ST is used to delimit the end of OSC style escape sequences

Other Escape Sequences

As these sequences start with an ESC, which is a C0 control, these will flush any buffered printable codepoints before triggering the associated action.

SeqNameDescriptionAction
ESC cRISReset to Initial StateResets tab stops, margins, modes, graphic rendition, palette, activates primary screen, erases the display and moves cursor to home position
ESC 7DECSCSave Cursor PositionRecords cursor position
ESC 8DECRCRestored Saved Cursor PositionMoves cursor to location it had when DECSC was used
ESC =DECPAMApplication KeypadEnable Application Keypad Mode
ESC >DECPNMNormal KeypadSet Normal Keypad Mode
ESC (0DEC Line Drawing character setTranslate characters j-x to line drawing glyphs
ESC (BUS ASCII character setDisables DEC Line Drawing character translation
ESC #8DECALNScreen Alignment DisplayFills the display with E characters for diagnostic/test purposes (for vttest)

CSI - Control Sequence Introducer Sequences

CSI sequences begin with the C1 CSI sequence, which is either the 7-bit ESC [ sequence or the codepoint 0x9B.

WezTerm classifies these sequences into a number of functional families which are broken out below.

Graphic Rendition (SGR)

SGR sequences are of the form CSI DIGITS [; DIGITS ]+ m. That is, any number of semicolon separated numbers, terminated by the m codepoint. There are a handful of slightly more modern sequences that use colon : codepoints to encode additional context.

The digits map to one of the codes in the table below, which manipulate the presentation attributes of subsequently printed characters.

It is valid to omit the code number; for example CSI m is equivalent to CSI 0 m which resets the presentation attributes.

CodeDescriptionAction
0ResetReset to default foreground/background colors, reset all presentation attributes, clear any explicit hyperlinks
1IntensityBoldSet the intensity level to Bold. This causes subsequent text to be rendered in a bold font variant and, if the foreground color is set to a palette index in the 0-7 range, effectively shifts it to the brighter value in the 8-15 range
2IntensityDimSet the intensity level to Dim or Half-Bright. This causes text to be rendered in a lighter weight font variant
3ItalicOnSets the italic attribute on the text, causing an italic font variant to be selected
4UnderlineOnText will have a single underline
4:0UnderlineOffText will have no underline
4:1UnderlineOnText will have a single underline
4:2UnderlineDoubleText will be rendered with double underline
4:3UnderlineCurlyText will be rendered with a curly underline
4:4UnderlineDottedText will be rendered with a dotted underline
4:5UnderlineDashedText will be rendered with a dashed underline
5BlinkOnIndicates that the text should blink <150 times per minute
6RapidBlinkOnIndicates that the text should blink >150 times per minute
7InverseOnCauses the foreground and background colors to be swapped
8InvisibleOnMarks text as invisible.
9StrikeThroughOnText will be rendered with a single line struck through the middle
21UnderlineDoubleText will be rendered with double underline
22NormalIntensityCancels the effect of IntensityBold and IntensityDim, returning the text to normal intensity
23ItalicOffCancels the effect of ItalicOn
24UnderlineOffText will have no underline
25BlinkOffCancels the effect of BlinkOn and RapidBlinkOn
27InverseOffCancels the effect of InverseOn
28InvisibleOffcancels the effect of InvisibleOn
29StrikeThroughOffCancels the effect of StrikeThroughOn
30ForegroundBlackSets the foreground color to ANSI Black, which is palette index 0
31ForegroundRedSets the foreground color to ANSI Red, which is palette index 1
32ForegroundGreenSets the foreground color to ANSI Green, which is palette index 2
33ForegroundYellowSets the foreground color to ANSI Yellow, which is palette index 3
34ForegroundBlueSets the foreground color to ANSI Blue, which is palette index 4
35ForegroundMagentaSets the foreground color to ANSI Magenta, which is palette index 5
36ForegroundCyanSets the foreground color to ANSI Cyan, which is palette index 6
37ForegroundWhiteSets the foreground color to ANSI White, which is palette index 7
39ForegroundDefaultSets the foreground color to the user's configured default text color
40BackgroundBlackSets the background color to ANSI Black, which is palette index 0
41BackgroundRedSets the background color to ANSI Red, which is palette index 1
42BackgroundGreenSets the background color to ANSI Green, which is palette index 2
43BackgroundYellowSets the background color to ANSI Yellow, which is palette index 3
44BackgroundBlueSets the background color to ANSI Blue, which is palette index 4
45BackgroundMagentaSets the background color to ANSI Magenta, which is palette index 5
46BackgroundCyanSets the background color to ANSI Cyan, which is palette index 6
47BackgroundWhiteSets the background color to ANSI White, which is palette index 7
49BackgroundDefaultSets the background color to the user's configured default background color
53OverlineOnRenders text with a single overline/overbar
55OverlineOffCancels OverlineOn
59UnderlineColorDefaultResets the underline color to default, which is to match the foreground color
90ForegroundBrightBlackSets the foreground color to Bright Black, which is palette index 8
91ForegroundBrightRedSets the foreground color to Bright Red, which is palette index 9
92ForegroundBrightGreenSets the foreground color to Bright Green, which is palette index 10
93ForegroundBrightYellowSets the foreground color to Bright Yellow, which is palette index 11
94ForegroundBrightBlueSets the foreground color to Bright Blue, which is palette index 12
95ForegroundBrightMagentaSets the foreground color to Bright Magenta, which is palette index 13
96ForegroundBrightCyanSets the foreground color to Bright Cyan, which is palette index 14
97ForegroundBrightWhiteSets the foreground color to Bright White, which is palette index 15
100BackgroundBrightBlackSets the background color to Bright Black, which is palette index 8
101BackgroundBrightRedSets the background color to Bright Red, which is palette index 9
102BackgroundBrightGreenSets the background color to Bright Green, which is palette index 10
103BackgroundBrightYellowSets the background color to Bright Yellow, which is palette index 11
104BackgroundBrightBlueSets the background color to Bright Blue, which is palette index 12
105BackgroundBrightMagentaSets the background color to Bright Magenta, which is palette index 13
106BackgroundBrightCyanSets the background color to Bright Cyan, which is palette index 14
107BackgroundBrightWhiteSets the background color to Bright White, which is palette index 15

There are a handful of additional SGR codes that allow setting extended colors; unlike the codes above, which are activated by a single numeric parameter out of SGR sequence, these the extended color codes require multiple parameters. The canonical representation of these sequences is to have the multiple parameters be separated by colons (:), but for compatibility reasons WezTerm also accepts an ambiguous semicolon (;) separated variation. The colon form is unambiguous and should be preferred; the semicolon form should not be used by new applications and is not documented here in the interest of avoiding accidental new implementations.

This sequence will set the foreground color to the specified palette INDEX, which can be a decimal number in the range 0-255.

CSI 38 : 5 : INDEX m

This sequence will set the background color to the specified palette INDEX, which can be a decimal number in the range 0-255.

CSI 48 : 5 : INDEX m

This sequence will set the underline color to the specified palette INDEX, which can be a decimal number in the range 0-255.

CSI 58 : 5 : INDEX m

This sequence will set the foreground color to an arbitrary color in RGB colorspace. The R, G and B symbols below are decimal numbers in the range 0-255. Note that after the 2 parameter two colons are present; its really an omitted colorspace ID parameter but that nature of that parameter is not specified in the accompanying ITU T.416 specification and is ignored by WezTerm and most (all?) other terminal emulators:

CSI 38 : 2 : : R : G : B m

(Since 20210814-124438-54e29167) For the sake of compatibility with some other terminal emulators this additional form is also supported where the colorspace ID argument is not specified:

CSI 38 : 2 : R : G : B m

This sequence will set the background color to an arbitrary color in RGB colorspace. The R, G and B symbols below are decimal numbers in the range 0-255:

CSI 48 : 2 : : R : G : B m

(Since 20210814-124438-54e29167) For the sake of compatibility with some other terminal emulators this additional form is also supported where the colorspace ID argument is not specified:

CSI 48 : 2 : R : G : B m

This sequence will set the underline color to an arbitrary color in RGB colorspace. The R, G and B symbols below are decimal numbers in the range 0-255:

CSI 58 : 2 : : R : G : B m

(Since 20210814-124438-54e29167) For the sake of compatibility with some other terminal emulators this additional form is also supported where the colorspace ID argument is not specified:

CSI 58 : 2 : R : G : B m

Cursor Movement

Editing Functions

Mode Functions

Since: 20210814-124438-54e29167

WezTerm supports Synchronized Rendering. DECSET 2026 is set to batch (hold) rendering until DECSET 2026 is reset to flush the queued screen data.

Device Functions

Window Functions

DCS - Device Control String

The C1 DCS escape places the terminal parser into a device control mode until the C1 ST is encountered.

In the table below, DCS can be either the 7-bit representation (ESC P) or the 8-bit codepoint (0x90).

SeqNameDescription
DCS $ q " p STDECRQSS for DECSCLRequest Conformance Level; Reports the conformance level
DCS $ q r STDECRQSS for DECSTBMRequest top and bottom margin report; Reports the margins
DCS $ q s STDECRQSS for DECSLRMRequest left and right margin report; Reports the margins
DCS [PARAMS] q [DATA] STSixel Graphic DataDecodes Sixel graphic data and apply the image to the terminal model. Support is preliminary and incomplete; see this issue for status.
DCS 1000 qtmux control modeBridges tmux into the WezTerm multiplexer. Currently incomplete, see this issue for status.

Operating System Command Sequences

Operating System Command (OSC) sequences are introduced via ESC ] followed by a numeric code and typically have parameters delimited by ;. OSC sequences are canonically delimited by the ST (String Terminator) sequence, but WezTerm also accepts delimiting them with the BEL control.

The table below is keyed by the OSC code.

OSCDescriptionActionExample
0Set Icon Name and Window TitleClears Icon Name, sets Window Title.\x1b]0;title\x1b\\
1Set Icon NameSets Icon Name, which is used as the Tab title when it is non-empty\x1b]1;tab-title\x1b\\
2Set Window TitleSet Window Title\x1b]2;window-title\x1b\\
3Set X11 Window PropertyIgnored
4Change/Query Color NumberSet or query color palette entries 0-255.query color number 1: \x1b]4;1;?\x1b\\
Set color number 2: \x1b]4;2;#cccccc\x1b\\
5Change/Query Special Color NumberIgnored
6iTerm2 Change Title Tab ColorIgnored
7Set Current Working DirectorySee Shell Integration
8Set HyperlinkSee Explicit Hyperlinks
9iTerm2 Show System NotificationShow a "toast" notificationprintf "\e]9;%s\e\\" "hello there"
52Manipulate clipboardRequests to query the clipboard are ignored. Allows setting or clearing the clipboard
104ResetColorsReset color palette entries to their default values
133FinalTerm semantic escapesInforms the terminal about Input, Output and Prompt regions on the displaySee Shell Integration
777Call rxvt extensionOnly the notify extension is supported; it shows a "toast" notificationprintf "\e]777;notify;%s;%s\e\\" "title" "body"
1337iTerm2 File Upload ProtocolAllows displaying images inlineSee iTerm Image Protocol
LSet Icon Name (Sun)Same as OSC 1\x1b]Ltab-title\x1b\\
lSet Window Title (Sun)Same as OSC 2\x1b]lwindow-title\x1b\\

Additional Resources