Terminal and Image Protocol Support for Yazi Previews

Updated

Yazi can preview images and highlighted code in most terminals, but image previews depend on your terminal supporting an image protocol. Yazi has built-in support for multiple image protocols and integrates with Überzug++, which the project describes as covering almost all terminals. Code highlighting is built in and works alongside image encoding and pre-caching, so normal file previews do not require a separate protocol. Before relying on image previews, confirm that your terminal supports one of the protocols Yazi can use.

What Yazi provides for previews

According to the Yazi project page, the file manager includes:

  • Built-in support for multiple image protocols — image previews are handled by Yazi itself rather than requiring an external preview tool.
  • Überzug++ integration — the project states this covers almost all terminals, which matters if your terminal lacks native image protocol support.
  • Built-in code highlighting and image encoding — combined with pre-caching, these accelerate both image and normal file loading.

The practical split is simple: text and code previews work through Yazi's built-in highlighting, while image previews require a compatible terminal or the Überzug++ path.

How to check whether your terminal will show image previews

  1. Identify your terminal emulator. Note the exact name and version, since protocol support varies by terminal and by version.
  2. Check whether it supports a native image protocol. Terminals that implement protocols such as Kitty's graphics protocol or Sixel can display images directly. The Yazi documentation lists the specific protocols and terminal compatibility, so check that page against your terminal rather than assuming.
  3. If there is no native protocol, plan on Überzug++. Yazi's integration with Überzug++ is the fallback the project presents as covering almost all terminals.
  4. Verify in practice. Open Yazi in the target terminal, navigate to a directory containing an image, and confirm the preview renders. Then open a source file to confirm highlighting appears.

Expected results

  • Code and text files: highlighted previews should appear without extra terminal configuration, since highlighting is built in.
  • Images: a preview should render if your terminal supports a protocol Yazi uses, or if Überzug++ is available and configured.
  • No image preview: this points to a terminal protocol gap or a missing Überzug++ setup, not a general failure of Yazi.

Common sticking points

  • Assuming every terminal works out of the box. "Almost all terminals" through Überzug++ is not the same as every terminal with no setup. Treat image preview as something to verify, not assume.
  • Testing only with text files. Code highlighting can work while image previews fail, so test both separately.
  • Ignoring terminal version. Protocol support can change between terminal releases; confirm against current Yazi documentation for your version.
  • Confusing speed with compatibility. Pre-caching and asynchronous I/O make previews load faster, but they do not add protocol support your terminal lacks.

Bottom line

If you mainly preview code and text, Yazi's built-in highlighting should work in a normal terminal setup. If image previews matter, check your terminal against Yazi's documented protocol support first, and fall back to the Überzug++ integration when native support is absent. Verify with one image and one code file before making it part of your workflow.