Why doesn't \x1b]4; ;rgb: take effect on text already on screen?

Terminal behaviour splits two ways. xterm and kitty repaint the entire screen when a palette index changes, so existing glyphs flip to the new colour immediately. gnome-terminal (VTE), iTerm2, alacritty, and wezterm only apply the new palette to subsequent draws — text already on the buffer keeps the colour it was rendered with. If you need a hard visual swap on a terminal that doesn't auto-repaint, force a full redraw with \x1b[2J\x1b[H (clear + home cursor) after the palette swap.

How do I reset one palette index without rewriting all 256?

Use OSC 104 — \x1b]104; \x07 resets index to the terminal's compiled-in default; \x1b]104\x07 (no parameter) resets all 256 indexes at once. xterm-ctlseqs documents the pair as the canonical inverse of OSC 4 — theme-appliers like pywal, base16-shell, and theme.sh emit OSC 104 with no parameter on teardown to restore the user's pre-theme palette.

OSC 4 — Set palette colour (and query)

Change one of the 256 palette colours, or query its current value.

Byte forms

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

\\x1b[\x1b]4;N;#RRGGBB\x07 (set) \x1b]4;N;?\x07 (query)

\\033[\033]4;N;...\007

\\e[\e]4;N;...\a

ESC [ESC ] 4 ; N ; COLOR BEL

hex1b 5d 34 3b <N> 3b ... 07

Description

Set the colour at index N (0..255) in the terminal's working palette. Indexes 0..7 are the basic colours (black / red / green / yellow / blue / magenta / cyan / white), 8..15 the bright variants, 16..231 the 6×6×6 colour cube, 232..255 the 24-step grayscale ramp. Colour syntax matches OSC 10/11: #RRGGBB, #RGB, rgb:RRRR/GGGG/BBBB, or X11 names. Replacing the colour with ? (\x1b]4;N;?\x07) makes the terminal reply with the current value — base16-themes, pywal, and theme-detectors all use this query/set loop to harvest and rewrite the palette at startup. Reset a single index with OSC 104 (\x1b]104;N\x07); reset the whole palette with OSC 104 with no parameter.

Spec citation: xterm-ctlseqs (OSC 4)

Examples

bash

printf '\033]4;1;#ff5555\007'   # remap colour 1 (red) to #ff5555\nprintf '\033]4;1;?\007'        # query current colour 1

python

import sys; sys.stdout.write('\x1b]4;1;#ff5555\x07')

fmt.Print("\x1b]4;1;#ff5555\x07")

javascript

process.stdout.write('\x1b]4;1;#ff5555\x07')

printf("\x1b]4;1;#ff5555\x07");

Used in

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

pywal (`wal -i image.jpg`)pywal extracts a 16-colour palette from an image then sweeps slots 0–15 across every open terminal via `\x1b]4;<n>;rgb:rr/gg/bb\x07` — running `wal` retones tmux, vim, ranger, and the bare shell all at once
base16-shell, base16-fzf live theme switch`base16_<theme>` sources a shell script that emits 16 OSC 4 escapes in sequence so a `base16_solarized-dark` → `base16_gruvbox-light` swap repaints every visible chunk of coloured terminal output without restarting the shell
xtermcontrol --get-color / --color<n>the `xtermcontrol` CLI is the canonical scriptable interface to OSC 4 — `xtermcontrol --get-color1` queries the current red palette slot via `\x1b]4;1;?\x07`, and `--color1 '#ff5555'` sets it
alacritty, kitty, WezTerm runtime colour reloadall three modern terminals support OSC 4 both for the standard 16 ANSI slots AND the extended 256-colour cube — `wezterm cli set-cwd` style commands repaint live without forcing a SIGUSR1 config reload
tmux `set -g terminal-overrides` palette passthroughtmux strips OSC by default; setting `terminal-overrides 'xterm*:RGB'` and `allow-passthrough on` lets a pywal-running inner pane re-tint the outer terminal so `base16_*` works inside tmux as if there were no multiplexer

Frequently asked

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

Why doesn't \x1b]4;<n>;rgb: take effect on text already on screen?: Terminal behaviour splits two ways. xterm and kitty repaint the entire screen when a palette index changes, so existing glyphs flip to the new colour immediately. gnome-terminal (VTE), iTerm2, alacritty, and wezterm only apply the new palette to subsequent draws — text already on the buffer keeps the colour it was rendered with. If you need a hard visual swap on a terminal that doesn't auto-repaint, force a full redraw with \x1b[2J\x1b[H (clear + home cursor) after the palette swap.
How do I reset one palette index without rewriting all 256?: Use OSC 104 — \x1b]104;<n>\x07 resets index <n> to the terminal's compiled-in default; \x1b]104\x07 (no parameter) resets all 256 indexes at once. xterm-ctlseqs documents the pair as the canonical inverse of OSC 4 — theme-appliers like pywal, base16-shell, and theme.sh emit OSC 104 with no parameter on teardown to restore the user's pre-theme palette.

Terminal support

xterm: yes
Linux console (fbcon): partial
macOS Terminal.app: partial
iTerm2: yes
Windows Terminal: yes
cmd.exe / ConPTY: no
kitty: yes
alacritty: yes
WezTerm: yes
Ghostty: yes
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	partial	partial	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes

Related sequences

In the family cookbook

SGR cookbook · 5. OSC palette override — repaint the slot itself