Yazi: The Terminal File Manager Replacing Ranger

You’re Still Using Ranger? Bless Your Heart

Look, Ranger is fine. It’s been fine since 2010. That’s also the problem.

If you’ve spent any time in terminal file managers, you know the drill: open Ranger, wait for Python to load, notice the preview pane is blank because you forgot to set up scope.sh, give up and use ls again. Or you tried Nnn, which is fast but minimalist to the point of being unusable for anything beyond “find the file, open the file.” Or you tried Lf, which is Ranger but written in Go, which is better but still needs a pile of config to do anything interesting.

Then Yazi showed up.

Yazi (pronounced “yazı,” Turkish for “writing”) is a terminal file manager written in Rust, and it is genuinely one of the few pieces of terminal software in the last five years that made me stop and go “oh, someone actually thought about this.” Version 0.4.x landed in late 2025 and it’s what I’d recommend anyone install today.

Here’s what actually changes when you use it.

Why Ranger Gets Annoying

Before you can appreciate Yazi, you need to feel Ranger’s paper cuts.

Startup time. Ranger is Python. On a slow machine or a busy system, ranger can take a full second to load. That doesn’t sound like much until you’re opening and closing it twenty times while navigating a messy project.

Preview setup is a chore. Ranger ships with scope.sh, a shell script that needs external tools (bat, ffmpegthumbnailer, mediainfo, highlight, etc.) all installed separately. If one is missing, that preview type silently doesn’t work. Good luck debugging it at 2 AM.

No async I/O. Ranger blocks on previews. Open a directory with a few thousand files and the UI freezes until it’s done. On NFS mounts or slow disks, this is genuinely painful.

Image previews are janky. Getting Kitty protocol image previews working in Ranger requires patching, external scripts, and prayer. Sometimes it works. Sometimes your terminal is just 40% of a cat photo.

Yazi solves all of these. Not with configuration, not with plugins. Out of the box.

What Yazi Actually Is

Yazi is an async-first terminal file manager. Everything that can block — directory reads, file previews, image rendering — runs in background tasks. The UI stays responsive. You keep navigating while previews load.

It uses the Kitty Graphics Protocol for image previews natively (with fallback to sixel, chafa, and Unicode half-blocks depending on your terminal). It supports syntax-highlighted file previews via bat, PDF and video thumbnails, and even renders Markdown in the preview pane.

The keybindings are Vim-style by default, close enough to Ranger that the muscle memory transfers in about ten minutes.

What you need:

# Arch (AUR: yazi-bin for prebuilt, yazi for source)
yay -S yazi-bin

# macOS
brew install yazi

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

# Also install these for full feature set
# bat — syntax highlighting in preview
# ffmpegthumbnailer — video thumbnails
# 7zip — archive preview
# jq — JSON preview
# poppler — PDF preview
# fd — faster file search
# ripgrep — search inside files
# imagemagick — image info

That’s the install list if you want everything. Yazi works without any of them — the previews just gracefully degrade. That’s already better than Ranger’s silent failures.

First Run, Five Minutes In

yazi ~/projects

You get a three-pane layout: parent directory on the left, current directory in the middle, preview on the right. Navigate with hjkl or arrow keys. Enter directories with l or Enter. Go back with h.

The default config is actually usable. This is rare. Most terminal software ships with defaults that are clearly a proof of concept and then expects you to write 200 lines of config before it’s usable. Yazi’s defaults are solid.

A few things you’ll notice immediately:

• Image previews just work if you’re on Kitty, WezTerm, or any terminal with the Kitty Graphics Protocol
• Syntax-highlighted code previews appear without any config if bat is installed
• Directory sizes show up (asynchronously — they populate while you’re browsing, not before)
• The status bar at the bottom gives you useful info: permissions, size, modification time

Configuration That’s Worth Knowing

Yazi uses TOML files in ~/.config/yazi/. The main ones are:

~/.config/yazi/
├── yazi.toml      # core settings
├── keymap.toml    # keybindings
└── theme.toml     # colors

yazi.toml — the settings that matter:

[manager]
ratio = [1, 3, 4]          # column width ratio: parent / current / preview
sort_by = "natural"         # natural sort (so file10 comes after file9)
sort_sensitive = false
sort_reverse = false
linemode = "size"           # show file sizes in the listing
show_hidden = false         # toggle with . at runtime
show_symlink = true

[preview]
tab_size = 2
max_width = 1200
max_height = 900
cache_dir = ""              # defaults to system cache dir

[opener]
# Define how to open file types
edit = [
  { run = 'nvim "$@"', block = true }
]

[open]
rules = [
  { mime = "text/*", use = "edit" },
  { mime = "application/json", use = "edit" },
  { mime = "image/*", use = "open" },
]

The linemode option is nice. You can set it to "size", "permissions", "mtime", or "none". You can also toggle it at runtime with M and cycle through modes.

The Plugin System Is Actually Good

Here’s where Yazi pulls ahead of both Ranger and Lf. It has a real plugin system with a Lua API (Yazi 0.3+ uses Lua 5.4), and the community has built genuinely useful plugins.

Installing plugins with the CLI:

# yazi-cli is installed alongside yazi-fm
ya pack -a yazi-rs/plugins#max-preview   # bigger preview pane hotkey
ya pack -a yazi-rs/plugins#smart-filter  # filter in current dir as you type
ya pack -a yazi-rs/plugins#starship      # starship prompt in status bar

The ya CLI manages plugins similar to how lazy.nvim handles Neovim plugins. Plugins go to ~/.config/yazi/plugins/.

A plugin worth installing day one — git.yazi:

ya pack -a yazi-rs/plugins#git

Add to ~/.config/yazi/init.lua:

require("git"):setup()

And to your keymap:

[[manager.prepend_keymap]]
on = ["g", "s"]
run = "plugin git --args=status"
desc = "Git status"

Now you can see modified/untracked/staged status in the file listing. It’s the kind of thing Ranger users have been hacking together with shell scripts for years. In Yazi it’s a plugin install and two config lines.

Keybindings: The Parts That Actually Differ from Ranger

If you’re coming from Ranger, 90% of the muscle memory transfers. The differences worth knowing:

The bulk rename workflow in Yazi is notably better than Ranger. Press r, select files with space, and it opens your $EDITOR with a list of filenames. Edit the names in your editor (yes, Neovim), save and quit, and Yazi renames the files. No separate vidir install needed.

Integrating with Your Shell

The shell integration is worth setting up. Yazi can change your working directory when you quit, so you land in whatever folder you were browsing. Without it, you quit back to wherever you started, which defeats half the point.

For zsh/bash:

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"
}

For fish:

function y
  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

Now use y instead of yazi. When you quit with q, your shell moves to the directory you were in. This is the correct behavior and it’s slightly annoying that it needs a wrapper function, but it’s a one-time setup.

Actual Performance Numbers

Here’s the thing that makes Rust tools worth switching to: startup time.

# Ranger (Python, on a reasonably fast machine)
time ranger --cmd quit
# real: 0m0.847s

# Yazi
time yazi --cmd quit
# real: 0m0.048s

That’s roughly 18x faster to start. On a busier machine or a slower disk, the gap is larger, not smaller. The async I/O means navigating into a directory with 10,000 files doesn’t freeze the UI — it shows you the files it has and keeps loading.

For large directories that would make Ranger stall, Yazi just… works.

Where Yazi Isn’t Perfect Yet

Honest assessment, because nothing is:

Remote file systems. SFTP browsing isn’t built in. Ranger has plugins for it that work okay. For now, if you need to browse remote paths, mount them with SSHFS first.

The ecosystem is younger. Ranger has been around since 2010. There are hundreds of Ranger plugins, scripts, and integrations. Yazi’s plugin ecosystem is growing fast but if you have a specific Ranger plugin you rely on, check before you switch.

Config migration isn’t automatic. There’s no ranger2yazi migration tool. You’ll spend an afternoon rewriting your config in TOML/Lua. For most people this is a net positive (the old config was a mess anyway), but it’s effort.

Documentation is good but scattered. The official docs at yazi.rs are decent, but some plugin docs are README-only in GitHub repos. You’ll be reading source code occasionally.

Should You Bother?

If you’re using Ranger daily, yes. The switch takes an afternoon and you’ll immediately notice the speed difference. The async previews alone are worth it if you work with image directories or codebases with lots of files.

If you’re on Nnn or Lf by choice because you specifically want a minimal fast manager, Yazi is heavier than Nnn but faster than Lf in practice. The image previews and plugin system make it worth the extra weight if you want those features.

If you’ve never used a terminal file manager and you’re used to GUI tools: Yazi is the best entry point in 2026. The defaults are sensible, the preview pane is impressive enough to actually sell someone on the concept, and you won’t spend three hours debugging why your file type associations aren’t working.

The honest test: open a directory with a thousand mixed files and images. In Ranger, watch it chug. In Yazi, you’re already three directories deep before Ranger would have finished rendering.

That’s the whole argument.

# One-liner to get started
yay -S yazi-bin bat fd ripgrep && yazi ~

That’s it. Navigate with hjkl, hit q to quit, set up the shell function above. You’re 80% of the way there in under five minutes.

The Bottom Line

Yazi is what happens when someone looks at the terminal file manager landscape, notices everything is either slow (Ranger), minimal (Nnn), or nearly-right (Lf), and decides to fix it properly. The Rust rewrite-for-performance angle is well-deserved here: the async architecture actually changes how the tool feels to use, not just how fast it starts.

Install it. Give it a week. The config is less painful than Ranger’s and the results are noticeably better. If you’re still running ls -la because file managers were always too annoying to set up, Yazi is the first one that might actually stick.

Related Reading

• Difftastic: Structural Diff That Makes Sense
• gitui vs lazygit: Two Git TUIs Compared
• Mise Deep Dive: Tasks, Tools, Env Vars
• Wezterm vs Alacritty vs Kitty: Modern Terminals
• Atuin: Shell History That Actually Works Across Machines