DEV Community

Recca Tsai
Recca Tsai

Posted on • Originally published at recca0120.github.io

yazi: Rust Terminal File Manager with Image Preview — Alacritty Fix Included

#yazi #terminal #rust #filemanager

Originally published at recca0120.github.io

Managing files in the terminal means chaining ls, cd, cp, mv back and forth.
You want something like Finder — quick browsing, image previews — without leaving the terminal.
yazi is that. Vim keybindings, written in Rust, fast.

What yazi Is

yazi (Chinese for "duck") is a terminal file manager written in Rust, built around non-blocking async I/O. File operations, previews, and thumbnails all run in the background — the UI doesn't freeze.

Key features:

  • Image preview: kitty, iTerm2, WezTerm, Sixel, and more
  • Syntax highlighting: built-in, no external tools needed
  • Multi-format preview: video thumbnails (FFmpeg), PDF (poppler), archives, directory trees
  • Vim keybindings: h/j/k/l navigation, / search, visual mode for batch selection
  • Lua plugins: highly customizable UI, active plugin ecosystem
  • Tool integration: fzf, zoxide, ripgrep, fd

Installation 

# macOS
brew install yazi ffmpeg sevenzip jq poppler fd ripgrep fzf zoxide imagemagick

# Arch Linux
pacman -S yazi ffmpeg p7zip jq poppler fd ripgrep fzf zoxide imagemagick

# Ubuntu / Debian (official packages are outdated — use the binary)
curl -LO https://github.com/sxyazi/yazi/releases/latest/download/yazi-x86_64-unknown-linux-musl.zip
unzip yazi-*.zip && sudo mv yazi-*/yazi /usr/local/bin/

# Cargo
cargo install yazi-fm yazi-cli
Enter fullscreen mode Exit fullscreen mode

The only hard dependency is the file command (usually pre-installed). Everything else (ffmpeg, poppler, etc.) is optional — install what you need for the preview formats you want.

Basic Usage 

yazi
Enter fullscreen mode Exit fullscreen mode
Key Action
h / ← Parent directory
l / → Enter directory / open file
j / k Move down / up
gg / G Jump to top / bottom
Space Toggle selection
y Copy
d Cut
p Paste
D Move to trash
r Rename
/ Search current directory
f fzf jump
z zoxide jump
q Quit and cd to current directory

Shell Integration: cd on Exit

Add a wrapper function so your shell follows yazi to whatever directory you navigated to:

# ~/.bashrc or ~/.zshrc
function yy() {
    local tmp="$(mktemp -t "yazi-cwd.XXXXXX")" cwd
    yazi "$@" --cwd-file="$tmp"
    if cwd="$(command cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        builtin cd -- "$cwd"
    fi
    rm -f -- "$tmp"
}
Enter fullscreen mode Exit fullscreen mode 
# ~/.config/fish/functions/yy.fish
function yy
    set tmp (mktemp -t "yazi-cwd.XXXXXX")
    yazi $argv --cwd-file="$tmp"
    if set cwd (command cat -- $tmp); and [ -n "$cwd" ]; and [ "$cwd" != "$PWD" ]
        builtin cd -- $cwd
    end
    rm -f -- $tmp
end
Enter fullscreen mode Exit fullscreen mode

Use yy instead of yazi. When you quit, your shell is already in the right directory.

Image Preview: Terminal Support

yazi auto-detects the terminal and picks the best image protocol. Check what it detected:

yazi --debug 2>&1 | grep Adapter
# Adapter.matches: Kgp    ← kitty protocol
# Adapter.matches: Iip    ← iTerm2/WezTerm inline protocol
# Adapter.matches: Sixel
Enter fullscreen mode Exit fullscreen mode
Terminal Method
kitty Kitty unicode placeholders (best)
iTerm2 / WezTerm / Ghostty Inline images protocol
foot / Windows Terminal Sixel
Alacritty No native protocol support (see below)

Alacritty Image Preview

Alacritty supports no image protocol — no kitty, no Sixel. yazi shows no images by default. The fix depends on your platform:

macOS: Chafa

On macOS, Überzug++'s X11/Wayland backend is disabled at compile time, so it can't overlay images. yazi automatically falls back to Chafa, which renders images using Unicode block characters inside the terminal.

Chafa is usually installed alongside yazi. Check:

which chafa  # /opt/homebrew/bin/chafa
Enter fullscreen mode Exit fullscreen mode

If not installed:

brew install chafa
Enter fullscreen mode Exit fullscreen mode

Verify yazi picks it up:

yazi --debug 2>&1 | grep Adapter
# Adapter.matches: Chafa
Enter fullscreen mode Exit fullscreen mode

Chafa in the output means image preview is active. Open yazi and you'll see it. Quality is character-based simulation rather than real pixels, but it works fine in a terminal.

Linux: Überzug++

Linux has X11 or Wayland, so Überzug++ can overlay actual images on top of the terminal window — much better quality than Chafa.

# Arch
pacman -S ueberzugpp

# Ubuntu (via openSUSE repo — see https://github.com/jstkdng/ueberzugpp)
Enter fullscreen mode Exit fullscreen mode

yazi auto-detects after installation:

yazi --debug 2>&1 | grep Adapter
# Adapter.matches: X11
# or
# Adapter.matches: Wayland
Enter fullscreen mode Exit fullscreen mode

Fine-tuning (optional)

Überzug++ overlays externally, so positioning can drift slightly. Adjust in ~/.config/yazi/yazi.toml:

[preview]
ueberzug_scale = 1.0           # > 1 enlarges, < 1 shrinks
ueberzug_offset = [0, 0, 0, 0] # position offset in character cells [x, y, w, h]
Enter fullscreen mode Exit fullscreen mode

Then: yazi --clear-cache

Image Preview Inside tmux

Works for both Chafa and Überzug++. Add to ~/.tmux.conf:

set -g allow-passthrough on
set -ga update-environment TERM
set -ga update-environment TERM_PROGRAM
Enter fullscreen mode Exit fullscreen mode

Configuration Files 

~/.config/yazi/
├── yazi.toml      # main config (preview, behavior)
├── keymap.toml    # keybindings
├── theme.toml     # colors and appearance
└── plugins/       # Lua plugins
Enter fullscreen mode Exit fullscreen mode

Install themes and plugins with the ya package manager:

# Install a theme
ya pack -a yazi-rs/flavors#catppuccin-mocha

# Install git status plugin
ya pack -a yazi-rs/plugins#git
Enter fullscreen mode Exit fullscreen mode

Summary

yazi is noticeably faster than ranger or lf, mainly because of the async architecture. Once you're used to the vim keybindings, most file operations happen without leaving the terminal.

Alacritty users: on macOS, install Chafa and yazi picks it up automatically. On Linux, Überzug++ gives real image quality instead of character simulation. Either way, no extra configuration — install the tool and open yazi.

References

Top comments (0)