Why your colors look wrong in tmux

Your editor theme is beautiful in a bare terminal and looks like a 1998 xterm inside tmux. This is the most-cargo-culted problem in the ecosystem — here's the actual mechanism, then the three lines that fix it.

The mechanism (30 seconds)

Terminals advertise their capabilities through $TERM. tmux sits in the middle: to the programs inside it, *tmux* is the terminal (so $TERM inside must be tmux's own value); to your real terminal, tmux is just a program (so tmux needs to know what the outer terminal can do). Colors break when either side of that handshake is wrong.

The fix

Two lines in .tmux.conf cover both directions:

~/.tmux.conf

set -g default-terminal "tmux-256color"   # inside: what programs see
set -ga terminal-features ",*:RGB"        # outside: outer terminal does 24-bit

Verify it worked

Restart tmux fully (tmux kill-server — sourcing isn't enough for default-terminal), then: echo $TERM inside should print tmux-256color, and this gradient should be smooth, not stepped:

true-color test — run inside tmux

awk 'BEGIN{for(i=0;i<77;i++){r=255-i*3;printf "\033[48;2;%d;%d;%dm ",r,i*3,i*2}print "\033[0m"}'

The decision tree when it still fails

1) echo $TERM *outside* tmux — if it's not what your terminal ships (e.g. xterm-256color, xterm-kitty), your shell config is overriding it; stop doing that. 2) echo $TERM *inside* — if it isn't tmux-256color, your default-terminal line isn't being read (wrong config path? tmux ≥ 3.1 also reads ~/.config/tmux/tmux.conf). 3) tmux info | grep -iE 'RGB|Tc' — no match means the terminal-features line didn't apply to your outer $TERM; the ,*:RGB wildcard form above applies to all of them. 4) vim/neovim specifically: set termguicolors (vim also needs t_8f/t_8b overrides; neovim doesn't).

Stale advice to ignore

set -g default-terminal "screen-256color" (loses italics and features — from the pre-tmux-terminfo era). terminal-overrides ',*256col*:colors=256' alone (256 indexed colors is not true color). Anything mentioning Tc still works as the older spelling of RGB but if the guide says Tc, check its date. And if a Mac guide mentions installing ncurses to get tmux-256color terminfo — that one's actually still occasionally true on old macOS versions, which is why tmux info verification beats faith.

Verified against tmux 3.6 · updated July 2026 · more guides · cheat sheet