Why does the same \x1b[48;2;…m background look washed-out on macOS Terminal but correct on iTerm2?

macOS Terminal.app silently quantizes 24-bit RGB down to its 256-colour palette before rendering, and never advertises $COLORTERM=truecolor even when set manually — so probe-based fallback paths don't trigger. iTerm2, kitty, alacritty, wezterm, ghostty, and Windows Terminal render true 24-bit. The fix is renderer-side: detect Terminal.app via $TERM_PROGRAM=Apple_Terminal (or the absence of $COLORTERM=truecolor) and emit a 256-cube fallback (\x1b[48;5;Nm) computed from your RGB triplet.

SGR 48;2;R;G;B — 24-bit truecolor background

Pick any of 16,777,216 background RGB colors directly.

Byte forms

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

\\x1b[\x1b[48;2;R;G;Bm

\\033[\033[48;2;R;G;Bm

\\e[\e[48;2;R;G;Bm

ESC [ESC [ 4 8 ; 2 ; R ; G ; B m

hex1b 5b 34 38 3b 32 3b ... 6d

Live preview

Rendered in your browser via the same tokeniser the decoder uses — no terminal needed.

255,100,50 / 100,200,255 / 180,120,255

Description

Background sibling of sgr-fg-truecolor (\x1b[38;2;R;G;Bm). R, G, B are each 0–255 — 16,777,216 distinct background hues. The semicolon form is the de-facto standard; the ECMA-48-compliant colon form \x1b[48:2::R:G:Bm (the empty 4th sub-parameter denotes the default colorspace ID per ITU-T T.416) is accepted by xterm, kitty, alacritty, wezterm and most modern emulators. The extension dates to xterm 282 (Sep 2013) and is documented in xterm-ctlseqs §"Direct color"; ECMA-48 itself standardizes only the indexed forms via SGR 48 + sub-parameter 5.

Always probe $COLORTERM (truecolor or 24bit) before emitting truecolor backgrounds in cross-environment code — terminals that lack support do not all behave the same way. Apple Terminal.app quantizes silently to the nearest 256-color slot, often producing muddy backgrounds for vibrant inputs, and does not advertise truecolor via $COLORTERM even when the user has set it manually. Linux console / fbcon ignores the escape entirely. Windows conhost.exe quantizes to 16 colors below ConPTY 1809+; modern Windows Terminal renders true 24-bit. screen 4.x quantizes; screen 5.0 forwards correctly. tmux requires set -ag terminal-overrides ',xterm-256color:RGB' (or the modern Tc cap) to forward truecolor — without it the truecolor bytes reach tmux but are quantized before they leave. iTerm2, kitty, alacritty, wezterm, ghostty, gnome-terminal 3.12+ and konsole all render truecolor backgrounds natively.

Reset just the background with \x1b[49m — surgical, leaves foreground and other attributes intact. The full reset \x1b[0m clears everything. For full theme honesty, pair a truecolor background with a contrasting truecolor foreground that you computed yourself rather than letting the user's default foreground sit over your custom background — the WCAG-AA contrast rule applies to terminal output too. To downgrade gracefully on unknown terminals, the standard pattern is if [ "$COLORTERM" = truecolor ]; then printf '\\x1b[48;2;%d;%d;%dm' …; else printf '\\x1b[48;5;%dm' …; fi with an RGB-to-256-cube helper for the fallback path — the same logic ships in chalk, colorama, crossterm and most other library truecolor probes.

Spec citation: ITU-T T.416 / xterm-ctlseqs (Direct color)

Examples

bash

printf '\033[48;2;30;30;30;38;2;255;200;0m on graphite \033[0m\n'

python

print('\x1b[48;2;30;30;30m bg \x1b[0m')

fmt.Print("\x1b[48;2;30;30;30m bg \x1b[0m")

javascript

console.log('\x1b[48;2;30;30;30m bg \x1b[0m')

printf("\x1b[48;2;30;30;30m bg \x1b[0m\n");

Used in

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

vim, neovim with `set termguicolors`switches all background highlight groups from cterm to gui 24-bit
bat, delta TrueColor themesexact palette match to the corresponding VS Code / TextMate theme
starship — branded prompt segment bgs
gh (GitHub CLI)PR-status and review-state badges use GitHub brand bgs
lipgloss / charmbracelet apps — gradient backgrounds on TUIs

Frequently asked

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

Why does the same \x1b[48;2;…m background look washed-out on macOS Terminal but correct on iTerm2?: macOS Terminal.app silently quantizes 24-bit RGB down to its 256-colour palette before rendering, and never advertises $COLORTERM=truecolor even when set manually — so probe-based fallback paths don't trigger. iTerm2, kitty, alacritty, wezterm, ghostty, and Windows Terminal render true 24-bit. The fix is renderer-side: detect Terminal.app via $TERM_PROGRAM=Apple_Terminal (or the absence of $COLORTERM=truecolor) and emit a 256-cube fallback (\x1b[48;5;Nm) computed from your RGB triplet.

Common typos / look-alikes

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

\x1b[48;5;255;0;0m\x1b[48;2;255;0;0m
Truecolor background uses the 2; sub-parameter, not 5;. 5; is the 256-colour palette prefix and takes a single index — \x1b[48;5;255;0;0m parses as palette index 255 followed by SGR 0 (reset) + SGR 0, so the background ends up white-ish and everything afterwards is unstyled. Mirrors the sgr-fg-truecolor mistake with 38;5;….
\x1b[48;2;#1e1e1em\x1b[48;2;30;30;30m
ANSI truecolor takes decimal R / G / B numerals separated by ; — hex strings like #1e1e1e are not parseable as SGR parameters. Convert hex → decimal triplet (#1e = 30) in your code before emitting. The terminal treats #1e1e1e as a giant unrecognised parameter and prints the literal bytes between the escapes.
emit truecolor unconditionally — assume every terminal renders itprobe $COLORTERM == truecolor || $COLORTERM == 24bit first; fall back to sgr-bg-256
Apple Terminal.app silently quantizes truecolor backgrounds to the nearest 256-palette slot, producing muddy results for vibrant inputs and *not* advertising truecolor via $COLORTERM even when the user has set it. Linux console / fbcon ignores the escape entirely. tmux requires set -ag terminal-overrides ',xterm-256color:RGB' (or the modern Tc cap) to forward truecolor — without it the bytes reach tmux but get quantized before leaving. The standard probe is if [ "$COLORTERM" = truecolor ] || [ "$COLORTERM" = 24bit ]; then printf '\x1b[48;2;%d;%d;%dm' …; else printf '\x1b[48;5;%dm' …; fi with a RGB→256-cube helper for the fallback — the same logic ships in chalk, colorama, crossterm.

Terminal support

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

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	partial	yes	yes	partial	yes	yes	yes	yes	yes	yes	partial	partial

Related sequences

In the family cookbook

SGR cookbook · 4. Truecolor — `\x1b[38;2;r;g;b m`