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 |
| Konsole | Kitty old protocol | ✅ Built-in |
| iTerm2 | Inline images protocol | ✅ Built-in |
| WezTerm | Inline images protocol | ✅ Built-in |
| Mintty (Git Bash) | Inline images protocol | ✅ Built-in |
| foot | Sixel graphics format | ✅ Built-in |
| Ghostty | Kitty old protocol | ✅ Built-in |
| Black Box | Sixel graphics format | ✅ Built-in |
| VSCode | Inline images protocol | ✅ Built-in |
| Tabby | Inline images protocol | ✅ Built-in |
| Hyper | Inline images protocol | ✅ Built-in |
| X11 / Wayland | Window system protocol | ☑️ Überzug++ required |
| Fallback | Chafa | ☑️ Überzug++ 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.
Zellij users
Zellij currently only supports the Sixel graphics format, so you will need a terminal that also supports Sixel.
Note that, the image rendering in Zellij has some performance issues, causing noticeable lagginess when quickly switching between images, and sometimes even image tearing.
These issues won't be improved until Zellij provides a passthrough mode or enhances Sixel rendering, if the image is a stronger need to you, consider running Yazi outside of Zellij or using Überzug++.
Windows users
Currently, only the following two terminals support displaying images on Windows:
- WezTerm
- Mintty (Git Bash, which comes with Git for Windows)
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 using 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 can't I preview images via Überzug++?
This may be an issue with Überzug++, please try running ueberzugpp layer directly in the terminal without Yazi, and paste:
{"action":"add","identifier":"preview","max_height":0,"max_width":0,"path":"/your/image-path.jpg","x":0,"y":0}
into it, then press Enter, and to see if any image is shown, without exiting the Überzug++. Note that you need to replace /your/image-path.jpg with the actual path of an image.
If the image shows properly when using Überzug++ independently, but not when used with Yazi, please create a bug report.
Why won't my images adapt to terminal size?
The size of the image depends on two factors:
- The max_width and max_height config options, which need to be adjusted by the user as needed.
- 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.