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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 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

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

1

yazi

Shell Integration: cd on Exit

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

1
2
3
4
5
6
7
8
9

# ~/.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"
}

1
2
3
4
5
6
7
8
9

# ~/.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

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:

1
2
3
4

yazi --debug 2>&1 | grep Adapter
# Adapter.matches: Kgp    ← kitty protocol
# Adapter.matches: Iip    ← iTerm2/WezTerm inline protocol
# Adapter.matches: Sixel

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:

1

which chafa  # /opt/homebrew/bin/chafa

If not installed:

1

brew install chafa

Verify yazi picks it up:

1
2

yazi --debug 2>&1 | grep Adapter
# Adapter.matches: Chafa

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.

1
2
3
4

# Arch
pacman -S ueberzugpp

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

yazi auto-detects after installation:

1
2
3
4

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

Fine-tuning (optional)

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

1
2
3

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

Then: yazi --clear-cache

Image Preview Inside tmux

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

1
2
3

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

Configuration Files

1
2
3
4
5

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

Install themes and plugins with the ya package manager:

1
2
3
4
5

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

# Install git status plugin
ya pack -a yazi-rs/plugins#git

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

• yazi official documentation
• yazi GitHub repository
• Chafa official website (character-based image renderer)
• Überzug++ GitHub repository (Linux image overlay tool)