XTPUSHCOLORS/XTPOPCOLORS
XTPUSHCOLORS and XTPOPCOLORS are XTerm extensions that save and restore the terminal's color palette using a stack.
Syntax
CSI # p XTPUSHCOLORS — Push color palette onto stack
CSI Ps # q XTPOPCOLORS — Pop color palette from stack
CSI # R XTREPORTCOLORS — Report palette stack depth
(* Push current palette onto stack *)
XTPUSHCOLORS = 0x1b, "[", "#", "p" ;
(* Pop palette from stack *)
XTPOPCOLORS = 0x1b, "[", [ Ps ], "#", "q" ;
(* Report current stack depth *)
XTREPORTCOLORS = 0x1b, "[", "#", "R" ;
(* Report response *)
XTREPORTCOLORS-response = 0x1b, "[", Pn, "#", "Q" ;
Ps = digit, { digit } ; (* stack entry to restore, default: pop top *)
Pn = digit, { digit } ; (* current stack depth *)
digit = "0" | "1" | "2" | "3" | "4"
| "5" | "6" | "7" | "8" | "9" ;Parameters
| Sequence | Parameter | Description |
|---|---|---|
XTPOPCOLORS | Ps | Stack entry index to restore (default: pop the most recent entry) |
Response (XTREPORTCOLORS)
The terminal responds with CSI Pn # Q where Pn is the number of entries currently on the palette stack.
Description
Per XTerm documentation, XTPUSHCOLORS saves the current color palette (all 256 indexed colors plus the dynamic colors like foreground, background, and cursor color) onto an internal stack. XTPOPCOLORS restores a previously saved palette.
The stack has a limited depth (typically 10 entries in XTerm). Pushing beyond the limit silently fails.
XTPOPCOLORS with no parameter pops the most recent entry, removing it from the stack. With a parameter Ps, it restores that specific stack entry without removing any entries.
XTREPORTCOLORS queries the current depth of the palette stack, allowing applications to check whether saves are available before popping.
These sequences are useful for applications that temporarily modify the terminal's color palette (such as theming or color scheme previews) and want to cleanly restore the original colors on exit.
Examples
# Save current color palette
printf '\e[#p'
# Modify some colors (e.g., set color 1 to bright red via OSC 4)
printf '\e]4;1;rgb:ff/00/00\e\\'
# Restore original color palette
printf '\e[#q'
# Query stack depth (response: ESC [ Pn # Q)
printf '\e[#R'
Specifications
| Specification | Section |
|---|---|
| XTerm ctlseqs | — |
Terminal support
| Terminal | Support | Version | Notes |
|---|---|---|---|
| Terminal Emulators | |||
| Alacritty | ✗ | No | |
| Bobcat | ✓ | 0.9.0 | Supported via TerminalCtrl library |
| contour | ✓ | v0.3.2.202 | |
| foot | ✓ | Yes | Implemented at csi.c:2124-2196, supports both XTPUSHCOLORS and XTPOPCOLORS |
| Ghostty | ✗ | No | Color palette stack operations not implemented |
| iTerm2 | ✓ | Yes | Color palette stack push/pop implemented via XTERMCC_XTPUSHCOLORS and XTERMCC_XTPOPCOLORS tokens (CSI # P and CSI # Q). |
| Kitty | ✓ | Yes | Implemented via CSI # p and CSI # Q |
| Konsole | ✗ | No | No implementation found for XTPUSHCOLORS/XTPOPCOLORS (CSI # p/q) |
| mintty | ✓ | Yes | Implemented at src/termout.c:3319-3325. Supports XTPUSHCOLORS (CSI # P), XTPOPCOLORS (CSI # Q), and XTREPORTCOLORS (CSI # R). |
| mlterm | ✗ | No | CSI # p/q not implemented |
| PuTTY | ✗ | No | Color palette stack (CSI # p/q) not implemented |
| Rio | ✗ | No | |
| rxvt-unicode | ✗ | No | |
| st | ✗ | No | |
| terminology | ✗ | No | No implementation found for color palette stack operations |
| VT100 | ✗ | No | |
| VTE | ✗ | No | Defined in parser but implementation is empty stub |
| WezTerm | ✗ | No | |
| Windows Terminal | ✗ | No | No evidence of XTPUSHCOLORS/XTPOPCOLORS implementation found |
| xterm | ✓ | xterm-385 | |
| xterm.js | ✗ | No | Tests marked as skipped with TODO |
| Multiplexers | |||
| cy | ✗ | No | |
| GNU Screen | ✗ | No | CSI # p/q not implemented |
| tmux | ✗ | No | Color palette stack not implemented; only title stack available |
| tuios | ✗ | No | |
| Zellij | ✗ | No | |
See also
- OSC 4 — Set/Query Color Palette — Modify individual palette colors
- OSC 104 — Reset Colors — Reset palette colors to defaults