Image Preview

Yazi has done a lot of work to adapt to different terminals and multiplexers, trying their best to make it out-of-the-box for users.

This is by no means a simple task, to reduce maintenance costs, we only guarantee it is available in the latest version of terminals and multiplexers (tmux, Zellij):

Platform	Protocol	Support
kitty	Kitty unicode placeholders	✅ Built-in
iTerm2	Inline images protocol	✅ Built-in
WezTerm	Inline images protocol	✅ Built-in
Konsole	Kitty old protocol	✅ Built-in
foot	Sixel graphics format	✅ Built-in
Ghostty	Kitty unicode placeholders	✅ Built-in
Windows Terminal (>= v1.22.2702.0)	Sixel graphics format	✅ Built-in
st with Sixel patch	Sixel graphics format	✅ Built-in
Tabby	Inline images protocol	✅ Built-in
VSCode	Inline images protocol	✅ Built-in
Rio	Inline images protocol	❌ Rio doesn't correctly clear images (#1786)
Black Box	Sixel graphics format	✅ Built-in
Hyper	Inline images protocol	✅ Built-in
X11 / Wayland	Window system protocol	☑️ Überzug++ required
Fallback	ASCII art (Unicode block)	☑️ Chafa required

Yazi automatically selects the appropriate preview method for you, based on the priority from top to bottom. That's relying on the $TERM, $TERM_PROGRAM, and $XDG_SESSION_TYPE variables, make sure you don't overwrite them by mistake!

For instance, if your terminal is Alacritty, which doesn't support displaying images itself, but you are running on an X11/Wayland environment, it will automatically use the "Window system protocol" to display images - this requires you to have Überzug++ installed.

tmux users

To enable Yazi's image preview to work correctly in tmux, add the following 3 options to your tmux.conf:

set -g allow-passthrough on
set -ga update-environment TERM
set -ga update-environment TERM_PROGRAM

Then restart tmux (important):

tmux kill-server && tmux || tmux

Now you should be able to enjoy with the image preview.

Note that if the protocol you are using is Sixel, make sure you passed --enable-sixel when building tmux, as it's disabled by default. You can verify this through tmux/tmux#4104.

Zellij users

Zellij currently only supports the Sixel graphics format, so you will need a terminal that also supports Sixel.

Note that, Zellij's Sixel implementation is quite buggy and has serious performance issues at the moment, causing noticeable lagginess when quickly switching between images, and sometimes even image tearing or not working at all.

These issues won't be improved until Zellij enhances it's Sixel implementation or provides a passthrough mode. If the image is a stronger need to you, consider running Yazi outside of Zellij or using Überzug++:

# Deceive Yazi into thinking you're running in Neovim,
# forcing it fallback to Überzug++ or Chafa
NVIM=1 NVIM_LOG_FILE=1 yazi

Windows users

Currently, only the following 2 terminals support displaying images on Windows:

• WezTerm
• Windows Terminal Preview v1.22.2702.0

Windows with WSL users

Limited by ConPTY, the Windows edition has had to implement many workarounds, which are not perfect.

However, if you run Yazi in WSL, you can experience perfect image previews through wezterm ssh.
WezTerm is an excellent terminal that can bypass the limitations of ConPTY through its SSH feature, and it's currently the only terminal that allows this approach.

You need to install sshd in WSL and start it:

sudo apt install openssh-server
sudo service ssh restart

Then, on the host machine, connect to WSL over SSH:

wezterm ssh 127.0.0.1

That's it! you can now get Yazi's image preview working properly.

Neovim users

The builtin terminal emulator (:term) in Neovim doesn't support any graphic protocols, so Yazi will try to fallback to X11/Wayland/Chafa in sequence.

Note that Überzug++ might display images in the wrong position; in that case, please adjust it manually using ueberzug_offset.

Why won't my images adapt to terminal size?

The size of the image depends on two factors:

1. The max_width and max_height config options, which need to be adjusted by the user as needed.
2. The pixel size of the terminal.

Yazi will use the smaller of these two factors as the image preview size.

However, some terminals (such as VSCode, Tabby, and all Windows terminals) don't implement the ioctl system call, before Add CSI 14 t sequence support is merged, it's not possible to obtain the actual pixel width and height of the terminal.

Hence, only max_width and max_height will be used in this case.

How can I know what image protocol Yazi uses?

Yazi provides a yazi --debug command that includes all your environment information, such as terminal emulator, image adapter, whether you're in SSH mode, etc.

Run it in the terminal where you want to preview images, and you'll see output like:

...
Adapter
    Adapter.matches: Kgp
...

which indicates the image protocol detected and used by Yazi:

Adapter.matches	Protocol	Notes
Kgp	Kitty unicode placeholders	Ensure your terminal is up to date to support it
KgpOld	Kitty old protocol	Doesn't work under tmux due to the limitations of the protocol itself
Iip	Inline images protocol	-
Sixel	Sixel graphics format	See tmux and Zellij section if you're using either of them
X11	Window system protocol	Überzug++ is required
Wayland	Window system protocol	Überzug++ is required and only supports Sway, Hyprland, and Wayfire
Chafa	ASCII art (Unicode block)	Chafa is required as the last fallback resort

Why can't I preview images via Überzug++?

This may be a problem with Überzug++ itself. Please build Yazi in debug mode as per this but cargo build without --release flag - you can run yazi --debug to verify it, and you will see the output includes Debug : true.

And hover on some images, then find the last Überzug++ command in your ~/.local/state/yazi/yazi.log sorted by time. It is usually at the very end of the file and looks like:

ueberzugpp command: {"action":"add","identifier":"yazi","x":96,"y":1,"max_width":400,"max_height":150,"path":"/root/test.jpg"}

Finally, run ueberzugpp layer directly in the terminal without and outside Yazi, and paste the command:

{"action":"add","identifier":"yazi","x":96,"y":1,"max_width":400,"max_height":150,"path":"/root/test.jpg"}

into it, press Enter, and to see if any image is shown, without exiting the Überzug++.

If the image shows properly when using Überzug++ independently, but not when used with Yazi, please create a bug report with:

• The contents of ~/.local/state/yazi/yazi.log
• The contents of /tmp/ueberzugpp-$USER.log
• A GIF demonstration of the above steps