TL;DR:

  • Yazi is a terminal file manager written in Rust that renders actual image thumbnails in supported terminals (Kitty, WezTerm, iTerm2), previews syntax-highlighted code, and doesn’t block the UI while loading large directories
  • It’s configured in TOML, scriptable in Lua, and integrates naturally with fd, ripgrep, and fzf for search
  • Installation is a single binary; startup is nearly instant; it replaces most of what people use ranger for with a notably better experience in modern terminals

There’s a category of developer tools you either use constantly or have never touched: terminal file managers. The case for them is that staying in the terminal — navigating, previewing, managing files, and dropping back into a shell command — is faster than alt-tabbing to Finder or Files, especially when you’re already deep in a session. The case against them historically has been that they’re fiddly to configure, slow to load large directories, and their file previews are limited to text.

Yazi, released in 2023 and now at version 0.4.x with stable APIs, addresses most of the historical objections. It’s become the default recommendation in terminal-centric development circles, and the image preview capability alone makes it something that’s hard to get with any other tool in the same category.

Async Everything

The headline architectural difference between Yazi and older tools like ranger is that Yazi is fully async. Ranger is Python-based and blocks: when you open a directory with thousands of files, the UI freezes while it loads. Yazi loads directory contents in the background and renders what it has while fetching the rest. The practical effect is that the UI feels instantaneous even for large directories — you can navigate while previews are still loading.

This also means file operations don’t block. If you’re copying a large set of files, Yazi queues the operation and continues letting you navigate and interact while it runs. Progress is shown in a task panel at the bottom of the screen.

Image Preview in the Terminal

This is Yazi’s most distinctive feature. In terminals that support pixel-level image rendering — Kitty, WezTerm, iTerm2, and foot via Sixel protocol — Yazi renders actual thumbnail previews of images as you navigate through them. Not ASCII art approximations. Actual rendered thumbnails.

It works via Kitty’s terminal graphics protocol (the gold standard for this), ueberzugpp for X11-based terminals, and Sixel for compatible terminals. The setup depends on your terminal:

  • Kitty: works out of the box, no configuration needed
  • WezTerm: works with protocol = "iterm2" in Yazi config
  • iTerm2: works with protocol = "iterm2" config
  • Standard terminals (GNOME Terminal, Alacritty): image preview not available; text previews still work

Even in terminals without image support, Yazi generates useful previews. Code files get syntax highlighting with Bat. PDFs are rendered to text via pdftoppm if installed. Archives show their contents. This makes it genuinely useful for browsing project directories, design assets, and mixed-content folders.

Installation and Basic Setup

# macOS
brew install yazi ffmpegthumbnailer unar jq poppler fd ripgrep fzf zoxide

# Arch Linux  
pacman -S yazi ffmpegthumbnailer unarchiver jq poppler fd ripgrep fzf zoxide

# Cargo (any platform with Rust installed)
cargo install --locked yazi-fm yazi-cli

The optional dependencies (ffmpegthumbnailer for video thumbnails, poppler for PDF preview, unarchiver for archive browsing) aren’t required but complete the experience.

Add a shell function to your .zshrc or .bashrc to have Yazi change your shell’s working directory when you quit:

function y() {
  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"
}

This is the standard setup and makes Yazi function as a proper shell integration rather than a separate application. You open it with y, navigate to where you want to be, press q, and your shell is in that directory.

Keybindings

The default keybindings follow Vim conventions. h/j/k/l for navigation, Enter to open, y to yank (copy path/selection to clipboard), p to paste, d to trash, D to delete permanently. Search within the current directory is /. Full-text search via ripgrep is s (with the search.lua plugin). Tab opens a second pane.

All keybindings are configurable in ~/.config/yazi/keymap.toml. The documentation includes a complete reference.

Plugins and Lua Scripting

Yazi has a Lua-based plugin system that’s well-developed by now. The Yazi.nvim plugin integrates it with Neovim so that when you open a file from Yazi, it opens in your active Neovim session. There are plugins for:

  • Jumping to bookmarked directories
  • Git status display in the file list
  • Full-text search with ripgrep integration
  • Archive extraction
  • Trash management with proper OS integration

The plugin ecosystem is at https://github.com/yazi-rs/plugins, and third-party plugins are indexed in the Yazi documentation.

How It Compares

vs ranger: Ranger is the most established Python-based terminal file manager. Yazi is faster, has better image preview, and has a cleaner configuration model. If you’ve been using ranger, migration is straightforward — the three-pane layout and general navigation model are the same.

vs lf: lf is minimal and fast, written in Go. Yazi is more opinionated and feature-complete out of the box, with image preview and plugin support that lf requires significant configuration to approach.

vs nnn: nnn is the smallest and fastest option, primarily for power users who want a pure keyboard-driven tool with minimal overhead. Yazi has more visual features; nnn has near-zero dependencies and is faster at pure navigation.

For most developers who spend significant time in terminals, Yazi is the point where terminal file management becomes genuinely compelling rather than just principled.