Yazi: a Rust terminal file manager built on async I/O

The problem Yazi targets: file browsing that does not stall on large directories

A terminal file manager is a small program with a hard constraint: it must keep the interface responsive while the filesystem is slow. Directory listings on network mounts, archive contents and image thumbnails all block a naive implementation. Yazi's answer is to make every I/O operation asynchronous and spread CPU work across multiple threads, as the README describes it, and to schedule file operations as managed tasks with progress reporting and cancellation rather than as blocking calls.

The audience follows from that. Yazi is for people who already work inside a terminal and want a navigator that does not force them back into a GUI when a directory is large. The README lists integration with ripgrep, fd, fzf and zoxide, which is a clear signal about who the project is written for: users who already have those tools installed and expect the file manager to compose with them rather than replace them.

It is not a general-purpose desktop file manager. There is no window, no system tray, and no drag-and-drop outside the terminal. The README does mention mouse support and drag and drop, but these are terminal-level features, documented at https://yazi-rs.github.io/docs/dnd, not desktop integration.

How Yazi works: async tasks, a client-server data service and a Lua plugin layer

The repository layout is unusually explicit about the architecture. The workspace has separate crates for the file manager binary (yazi-fm), the command-line companion (yazi-cli), the scheduler (yazi-scheduler), the virtual filesystem (yazi-vfs), the data distribution service (yazi-dds), the plugin host (yazi-plugin), the adapter layer for image protocols (yazi-adapter) and the terminal emulator (yazi-emulator). Reading the crate names tells you more about the design than the feature list does: file operations, previews and remote filesystems are not one module with branches, they are separate processes of concern with their own boundaries.

The data distribution service is the part worth understanding before you adopt. The README describes it as built on a client-server architecture with no additional server process required, integrated with a Lua-based publish-subscribe model, providing cross-instance communication and state persistence. In practice this means two Yazi instances can share state without you running a daemon. That is a real design decision, and it is also the source of the coupling between the plugin layer and the runtime: plugins subscribe to events from the same service the UI uses.

The plugin system is concurrent and covers more than decoration. The README lists UI plugins that can rewrite most of the interface, functional plugins, and custom previewer, preloader, spotter and fetcher plugins. A package manager installs plugins and themes with one command and can pin them to a specific version. The virtual filesystem is where remote file management and custom search engines live, which is the mechanism behind the SSH question people ask.

Installing Yazi and running a first real session

The README does not embed installation steps. It points to https://yazi-rs.github.io/docs/installation for usage, and the image preview details live at https://yazi-rs.github.io/docs/image-preview. The workspace Cargo.toml declares rust-version 1.95.0 and edition 2024, so a current Rust toolchain is the starting point, and the default members are yazi-fm and yazi-cli.

Two settings from the workspace Cargo.toml are worth knowing before you build. The release profile sets lto = true, codegen-units = 1, panic = "abort" and strip = true, so a release build is slow to compile and produces a stripped binary. Windows uses a separate profile, release-windows, which inherits release but sets panic = "unwind".

[profile.release]
codegen-units = 1
lto           = true
panic         = "abort"
strip         = true

Once built, the file manager is the yazi-fm binary and the companion CLI is yazi-cli. The companion is where the package manager lives: the README describes installing plugins and themes with one command and pinning them to a specific version. Theme and plugin files are Lua, so a first customization is a Lua file rather than a key-value config, and the repository ships .luarc.json and stylua.toml at the top level for editor and formatting support.

For previews, the README says X11 and Wayland users need Überzug++ and that the ASCII fallback requires Chafa 1.16.0 or newer. Those are external programs, not Cargo dependencies.

Where Yazi stops being the right tool

The README's own project status section is the most important paragraph in it: Yazi is a public beta, usable as a daily driver, in heavy development, with breaking changes expected. That is not a hedge, it is an operating constraint. If you configure Yazi heavily through plugins and then upgrade, the plugin API is the surface most likely to move, because the plugin host sits between the UI and the data distribution service and both are still evolving.

Image preview is the second boundary. The built-in protocols cover Kitty, iTerm2, WezTerm, Konsole, foot, Ghostty, Windows Terminal 1.22.10352.0 and newer, st with the Sixel patch, Warp on macOS and Linux, Tabby, VSCode, Rio 0.3.9 and newer, Black Box and Bobcat. Outside that list you are on Überzug++ or Chafa, and the fallback is Unicode block ASCII art. If you work over SSH into a terminal that does not negotiate one of those protocols, previews degrade to text, and the graphical part of Yazi's value proposition disappears.

Finally, the last push to the repository was on 2024-08-07. That date is not the release cadence: tagged releases exist well after it, including v26.8.15 on 2026-08-15 and v26.5.6 on 2026-05-05. Read the tags, not the commit graph, when you decide what to install.

Yazi compared with ranger and lf

The obvious alternatives are ranger and lf, and the difference is not cosmetic. Ranger is a Python application, and its preview and plugin model is built around Python modules loaded into the same interpreter that draws the interface. That makes plugins easy to write if you already know Python, and it makes the whole program subject to the interpreter's scheduling behaviour. Yazi takes the opposite route: Rust, a scheduler crate, and a plugin host that runs Lua pieces concurrently rather than in one interpreter loop.

lf goes the other way again. It is deliberately small, configured through environment variables and a shell-command model, and it treats the terminal as the rendering target rather than building its own abstraction over it. Yazi ships yazi-emulator, yazi-tty and yazi-tui as separate crates, which is a much heavier investment in controlling how the terminal is driven. The payoff is the image protocol matrix; the cost is more moving parts to understand when something renders wrong.

None of this makes ranger or lf worse choices. If your configuration is a few keybindings and you never preview an image, the extra machinery in Yazi is weight you are carrying for nothing.

Licence, maintenance and what an upgrade costs

Yazi is MIT-licensed, and the workspace Cargo.toml repeats license = "MIT" for the package metadata. The repository also carries a separate LICENSE-ICONS file, which means the icon assets are not necessarily covered by the same terms as the code. If you redistribute Yazi or bundle it into a product, read LICENSE-ICONS alongside LICENSE; that is a factual observation about the file layout, not legal advice, and a lawyer is the right person to interpret it.

Upgrade cost concentrates in three places. First, the plugin API, because the README states breaking changes are expected during heavy development. Second, the configuration files, which are Lua and therefore code rather than data. Third, the image adapter, because terminal graphics protocols are still moving and the README tracks minimum versions per terminal (Kitty 0.28.0, Windows Terminal 1.22.10352.0, Rio 0.3.9, Chafa 1.16.0). If you pin plugins to a specific version through the package manager, you trade freshness for a smaller upgrade surface, which is the reasonable choice for anyone running Yazi on more than one machine.

The release channel matters here too. The repository publishes nightly builds alongside tagged versions, and the nightly entry in the release list is dated the same day as the last push. Installing a nightly means opting into whatever landed that day.

Editorial conclusion

Adopt Yazi if you work in a terminal that supports Kitty graphics, iTerm2 inline images or Sixel, and you want a file manager whose plugin and theme layer is Lua rather than a config language you have to learn from scratch. Skip it if you need a stable configuration surface across upgrades, because the README states the project is in heavy development and that breaking changes should be expected. Before committing, check two things: whether your terminal appears in the image preview table at https://yazi-rs.github.io/docs/image-preview, and whether the release you install is a tagged version or a nightly build.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes