Skip to main content

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.

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

TerminalProtocolSupport
Kitty (>= 0.28.0)Kitty unicode placeholders✅ Built-in
GhosttyKitty unicode placeholders✅ Built-in
iTerm2Inline images protocol✅ Built-in
WezTermInline images protocol✅ Built-in
Warp (macOS/Linux)Inline images protocol✅ Built-in
VSCodeInline images protocol✅ Built-in
TabbyInline images protocol✅ Built-in
BobcatInline images protocol✅ Built-in
KonsoleKitty old protocol✅ Built-in
footSixel graphics format✅ Built-in
Windows Terminal (>= v1.22.10352.0)Sixel graphics format✅ Built-in
st with Sixel patchSixel graphics format✅ Built-in
Black BoxSixel graphics format✅ Built-in
RioInline images protocol❌ Renders at incorrect sizes
X11 / WaylandWindow system protocol☑️ Überzug++ required
FallbackASCII 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.

Build docs developers (and LLMs) love