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, 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.
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++.
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 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
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.