> ## 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.

# 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](https://github.com/kovidgoyal/kitty) (>= 0.28.0)                     | Kitty unicode placeholders | ✅ Built-in                    |
| [Ghostty](https://github.com/ghostty-org/ghostty)                            | Kitty unicode placeholders | ✅ Built-in                    |
| [iTerm2](https://iterm2.com)                                                 | Inline images protocol     | ✅ Built-in                    |
| [WezTerm](https://github.com/wez/wezterm)                                    | Inline images protocol     | ✅ Built-in                    |
| [Warp](https://www.warp.dev) (macOS/Linux)                                   | Inline images protocol     | ✅ Built-in                    |
| [VSCode](https://github.com/microsoft/vscode)                                | Inline images protocol     | ✅ Built-in                    |
| [Tabby](https://github.com/Eugeny/tabby)                                     | Inline images protocol     | ✅ Built-in                    |
| [Bobcat](https://github.com/ismail-yilmaz/Bobcat)                            | Inline images protocol     | ✅ Built-in                    |
| [Konsole](https://invent.kde.org/utilities/konsole)                          | Kitty old protocol         | ✅ Built-in                    |
| [foot](https://codeberg.org/dnkl/foot)                                       | Sixel graphics format      | ✅ Built-in                    |
| [Windows Terminal](https://github.com/microsoft/terminal) (>= v1.22.10352.0) | Sixel graphics format      | ✅ Built-in                    |
| [st with Sixel patch](https://github.com/bakkeby/st-flexipatch)              | Sixel graphics format      | ✅ Built-in                    |
| [Black Box](https://gitlab.gnome.org/raggesilver/blackbox)                   | Sixel graphics format      | ✅ Built-in                    |
| [Rio](https://github.com/raphamorim/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`:

```rust theme={null}
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:

```rust theme={null}
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`:

```toml theme={null}
[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:

```rust theme={null}
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:

```bash theme={null}
# 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):

```bash theme={null}
# 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?](https://yazi-rs.github.io/blog/why-is-yazi-fast) for architectural details.