Yazi provides built-in image preview support across a wide range of terminal emulators through multiple image protocols. It automatically detects your terminal and selects the best available protocol.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt
Use this file to discover all available pages before exploring further.
Supported Protocols
Yazi implements several image protocols to maximize terminal compatibility:- Kitty Graphics Protocol (KGP) - Modern unicode placeholders for efficient image rendering
- Kitty Old Protocol - Legacy Kitty graphics protocol for older versions
- Inline Images Protocol (IIP) - iTerm2-style inline images
- Sixel - Classic sixel graphics format with wide support
- Überzug++ - Window system protocol for X11/Wayland
- Chafa - ASCII art fallback using Unicode blocks
Terminal Compatibility
| Terminal | Protocol | Support |
|---|---|---|
| Kitty (>= 0.28.0) | Kitty unicode placeholders | ✅ Built-in |
| Ghostty | Kitty unicode placeholders | ✅ Built-in |
| iTerm2 | Inline images protocol | ✅ Built-in |
| WezTerm | Inline images protocol | ✅ Built-in |
| Warp (macOS/Linux) | Inline images protocol | ✅ Built-in |
| VSCode | Inline images protocol | ✅ Built-in |
| Tabby | Inline images protocol | ✅ Built-in |
| Bobcat | Inline images protocol | ✅ Built-in |
| Konsole | Kitty old protocol | ✅ Built-in |
| foot | Sixel graphics format | ✅ Built-in |
| Windows Terminal (>= v1.22.10352.0) | Sixel graphics format | ✅ Built-in |
| st with Sixel patch | Sixel graphics format | ✅ Built-in |
| Black Box | Sixel graphics format | ✅ Built-in |
| Rio | Inline images protocol | ❌ Renders at incorrect sizes |
| X11 / Wayland | Window system protocol | ☑️ Überzug++ required |
| Fallback | ASCII art (Unicode block) | ☑️ Chafa required (>= 1.16.0) |
How It Works
Yazi’s image adapter system automatically:- Detects your terminal using environment variables and capability queries
- Selects the best protocol from the compatibility list
- Handles image processing including decoding, resizing, and color management
- Manages image state for smooth preview updates
yazi-adapter/src/adapter.rs:88:
Image Processing
Yazi includes built-in image decoding and processing capabilities:Pre-caching
Images are pre-cached and optimized before display:Downscaling
Images are automatically downscaled to fit the preview area while respecting configured limits.Configuration
Configure image preview behavior in youryazi.toml:
Special Considerations
Tmux Support
Yazi automatically detects and handles Tmux by wrapping escape sequences:WSL Support
Windows Subsystem for Linux is automatically detected and handled appropriately.Color Management
Yazi supports ICC color profiles for accurate color reproduction when available.External Dependencies
Überzug++
For X11 and Wayland terminals without native protocol support:Chafa
For ASCII art fallback (version 1.16.0 or higher):Troubleshooting
No Images Showing
- Check terminal compatibility in the table above
- Verify image preview is enabled in config
- For Überzug++, ensure X11/Wayland is running
- Check file permissions on image files
Images at Wrong Size
Adjustmax_width and max_height in configuration to match your terminal’s capabilities.
Poor Image Quality
Increaseimage_quality setting (higher = better quality, larger cache files).
Performance
Image preview is highly optimized:- Async decoding - Images decode in background threads
- Pre-loading - Next images load before you navigate to them
- Smart caching - Processed images cached to disk
- Memory limits - Configurable bounds prevent excessive memory use