Image Preview

Built-in support for multiple image protocols across terminals

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.

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:

1. Detects your terminal using environment variables and capability queries
2. Selects the best protocol from the compatibility list
3. Handles image processing including decoding, resizing, and color management
4. Manages image state for smooth preview updates

The implementation is in yazi-adapter/src/adapter.rs:88:

pub fn matches(emulator: &Emulator) -> Self {
    let mut adapters: Adapters = emulator.into();
    if env_exists("ZELLIJ_SESSION_NAME") {
        adapters.retain(|p| *p == Self::Sixel);
    } else if TMUX.get() {
        adapters.retain(|p| *p != Self::KgpOld);
    }
    if let Some(p) = adapters.first() {
        return *p;
    }
    // ... fallback logic
}

Image Processing

Yazi includes built-in image decoding and processing capabilities:

Pre-caching

Images are pre-cached and optimized before display:

pub async fn precache(src: PathBuf, cache: &Path) -> Result<()> {
    let (mut img, orientation) = Self::decode_from(src).await?;
    let (w, h) = Self::flip_size(orientation, 
        (YAZI.preview.max_width, YAZI.preview.max_height));
    
    if img.width() > w || img.height() > h {
        img = img.resize(w, h, Self::filter());
    }
    if orientation != Orientation::NoTransforms {
        img.apply_orientation(orientation);
    }
    // ... encode and cache
}

Downscaling

Images are automatically downscaled to fit the preview area while respecting configured limits.

Configuration

Configure image preview behavior in your yazi.toml:

[preview]
# Maximum image dimensions (width x height in pixels)
max_width = 600
max_height = 900

# Image quality for JPEG encoding (0-100)
image_quality = 75

# Resize filter algorithm
# Options: nearest, triangle, catmull-rom, gaussian, lanczos3
image_filter = "triangle"

[tasks]
# Maximum memory allocation for image decoding (bytes, 0 = unlimited)
image_alloc = 536870912  # 512 MB

# Maximum image dimensions to decode [width, height]
image_bound = [0, 0]  # 0 = unlimited

Special Considerations

Tmux Support

Yazi automatically detects and handles Tmux by wrapping escape sequences:

if TMUX.get() {
    ESCAPE.set("\x1b\x1b");
    START.set("\x1bPtmux;\x1b\x1b");
    CLOSE.set("\x1b\\");
    Mux::tmux_passthrough();
}

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:

# Install via package manager
sudo apt install ueberzugpp  # Debian/Ubuntu
sudo pacman -S ueberzugpp    # Arch Linux

Chafa

For ASCII art fallback (version 1.16.0 or higher):

# Install via package manager
sudo apt install chafa  # Debian/Ubuntu
sudo pacman -S chafa    # Arch Linux
brew install chafa      # macOS

Troubleshooting

No Images Showing

1. Check terminal compatibility in the table above
2. Verify image preview is enabled in config
3. For Überzug++, ensure X11/Wayland is running
4. Check file permissions on image files

Images at Wrong Size

Adjust max_width and max_height in configuration to match your terminal’s capabilities.

Poor Image Quality

Increase image_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

See Why is Yazi Fast? for architectural details.