Image Preview Protocols

Yazi supports multiple terminal image protocols. The best protocol depends on your terminal emulator and tmux setup.

Protocol Support Matrix

Terminal	Protocol	Native	tmux Ready	Notes
Kitty	kitty (icat)	✅	Needs allow-passthrough	Fastest protocol; lossless
iTerm2	iterm2	✅	❌	Uses inline images
WezTerm	kitty	✅	❌	Implements Kitty protocol natively
Konsole	sixel	✅	Needs allow-passthrough	KDE's terminal
foot	sixel	✅	❌	Wayland-native terminal
Ghostty	kitty	✅	❌	Emerging terminal with Kitty protocol
Any terminal	Überzug++	❌ (wrapper)	✅	Python-based fallback for non-native terminals

Kitty Protocol vs. Sixel

Feature	Kitty (icat)	Sixel
Image quality	Lossless (PNG data)	Lossless (vector-like)
Transparency	✅	Limited
Speed	Very fast	Moderate
Terminal support	Kitty, WezTerm, Ghostty	Konsole, foot, Xterm
tmux compatibility	With allow-passthrough	With allow-passthrough

tmux Pass-Through

Both Kitty and Sixel require tmux pass-through to function inside tmux sessions:

# ~/.tmux.conf
set -g allow-passthrough on
set -ga update-environment TERM
set -ga update-environment TERM_PROGRAM

warning

Without allow-passthrough on, image previews will silently fail inside tmux.

Überzug++ Fallback

Überzug++ is a Python wrapper that draws images as terminal overlay elements. Use it when your terminal lacks native protocol support.

pip install ueberzug

Yazi auto-detects Überzug++ when no native protocol is available.

Pros	Cons
Works in almost any terminal	Slower than native protocols
tmux compatible	Requires Python + dependencies
No terminal config needed	Overlay can flicker on resize

See Also

• Image Preview Setup — per-terminal configuration guides
• tmux Integration — deeper tmux setup