Yazi: A Rust-Based Terminal File Manager Built on Async I/O

The Problem: Slow Terminal File Managers and Limited Previews

Terminal file managers often feel sluggish because file I/O and preview generation block the interface. Yazi addresses this by using non-blocking async I/O in Rust, which means file operations do not wait for each other. The target user is someone who lives in the terminal, manages remote files, or needs image previews without leaving the shell. Yazi also aims to be customizable through a plugin system, so it is for users who want to tweak the UI and behavior without forking the core. If you are happy with a basic file manager that just lists files, Yazi may be overkill. But if you have felt the lag in tools like ranger when previewing images or searching large directories, Yazi is designed to remove that friction.

How Async I/O and the Data Distribution Service Work

The core architecture is built on non-blocking async I/O. All I/O operations are asynchronous, and CPU-bound tasks are spread across multiple threads. This means that when you scroll through a directory with many files, the preview can load in the background without freezing the interface. The README points to an article titled "Why is Yazi Fast?" for internal details, but the visible mechanism is clear: async I/O plus a multi-threaded task scheduler. Yazi also includes a client-server architecture that does not require a separate server process. It uses a Lua-based publish-subscribe model for data distribution. This allows cross-instance communication and state persistence, meaning you can have multiple Yazi instances that share state, such as the current directory or selection. The virtual filesystem feature extends this: you can build custom VFS providers and search engines, which is useful for managing remote files as if they were local. The design is ambitious, and the dependency on Lua for plugins means you need to learn Lua to get the most out of it.

Getting Yazi Running: Installation and Configuration

The documentation is available at https://yazi-rs.github.io/docs/installation, but the README itself does not list specific install commands. From the repository layout, you can see it is a standard Rust project, so you can build from source using cargo build --release. There are also nightly builds released regularly, which you can download from the releases page. For configuration, Yazi uses a YAML-based config file, but the README does not show the exact keys. You will need to consult the docs for that. The package manager is a notable feature: you can install plugins and themes with one command, and pin them to a specific version. This is similar to a language package manager, which is unusual for a file manager. The README mentions integration with ripgrep, fd, fzf, and zoxide, so you may need to install those tools if you want those features. The image preview support depends on your terminal; for example, kitty uses the Kitty unicode placeholders protocol, while foot uses Sixel. If your terminal is not in the table, you can use Überzug++ on X11/Wayland or Chafa as a fallback, but those are external dependencies.

Built-In Image Protocols and Terminal Compatibility

Yazi has built-in support for a wide range of image protocols, covering most modern terminals. The README lists kitty, iTerm2, WezTerm, Konsole, foot, Ghostty, Windows Terminal, st with Sixel patch, Warp, Tabby, VSCode, Rio, Black Box, and Bobcat. Each uses a different protocol, such as Kitty unicode placeholders, Inline images, or Sixel. This is a strength because it removes the need for external image viewers in many cases. However, the protocol support is tied to terminal versions; for example, kitty must be at least 0.28.0, and Windows Terminal must be at least v1.22.10352.0. If you use an older terminal, you will need to rely on the fallback options: Überzug++ for X11/Wayland or Chafa for ASCII art. The fallback requires external tools, which adds setup complexity. The project also includes built-in code highlighting and image decoding, which accelerates preview loading, but this means Yazi bundles its own decoders, which could be a maintenance burden. The image preview is a key selling point, but it is only as good as your terminal's support.

The Lua Plugin System and Customization

Yazi's plugin system is concurrent and allows you to rewrite most of the UI, add functional plugins, and create custom previewers, preloaders, spotters, and fetchers. The plugins are written in Lua, which is a lightweight scripting language that is easy to embed. The README mentions UI plugins that can rewrite most of the UI, which suggests a high degree of customization. There is also a package manager to install plugins and themes, keeping them up to date or pinning them. This is a powerful feature for users who want to tailor the file manager to their workflow. However, the plugin system is complex. You need to learn Lua and understand the Yazi plugin API, which is not documented in the README. The project is in public beta, so the plugin API may change between versions, which could break your customizations. The README explicitly says to expect breaking changes. This is a significant trade-off: you get deep customizability, but you must be prepared to maintain your plugins as Yazi evolves.

Limitations and When Yazi Is the Wrong Tool

The most obvious limitation is that Yazi is in public beta and under heavy development. The README says to expect breaking changes, which means that upgrading Yazi could break your config, plugins, or themes. This is a serious consideration for a tool that you use daily. Another limitation is the image preview compatibility: if your terminal is not in the supported list and you do not want to install external dependencies like Überzug++ or Chafa, you will get no image previews. Yazi also relies on external integrations like ripgrep and fd for search and filtering, so you need to install those separately. The client-server architecture, while powerful, adds complexity, and the data distribution service may be overkill for simple single-instance use. Yazi is also not a good choice if you need a file manager that works over SSH with a simple terminal that lacks image support; you would be limited to ASCII previews. Finally, the multi-threaded async design means that on very old hardware with limited cores, the overhead of thread management might outweigh the benefits, though the README does not provide benchmarks to confirm this.

Alternative Approaches: ranger and lf

The most common alternative to Yazi is ranger, a Python-based terminal file manager that uses a different approach: it is synchronous and relies on external tools for previews, such as w3m for images. ranger has a simpler plugin system using Python, which may be easier for some users. Another alternative is lf, a Go-based file manager that is also asynchronous but has a more minimalist design. lf does not have built-in image previews; you have to configure external scripts. The key difference is that Yazi integrates image protocols directly and uses Rust for performance, while ranger and lf rely on external tools and are not as fast in terms of I/O. Yazi's plugin system is more powerful but also more complex. If you prefer a stable, mature tool with a large community, ranger might be better. If you want a lightweight and simple tool, lf could be sufficient. Yazi's advantage is performance and built-in features, but it comes at the cost of beta stability.

Maintenance, Upgrades, and License

Yazi is MIT-licensed, which means you can use, modify, and distribute it freely, with attribution. This is a permissive license, so you can even fork it if you need to patch something. The project is actively maintained, with recent releases including a nightly build from 2024-08-07 and version v26.8.15 from 2026-08-15. The version numbering is unusual, but it suggests continuous development. The README mentions that the project is in heavy development, so you should expect frequent updates. The package manager helps with upgrades, but it also means you need to stay on top of updates to get bug fixes and new features. The maintenance cost is moderate: you need to update Yazi regularly, and you may need to adjust your config or plugins when breaking changes occur. The documentation is available online, but it is not exhaustive in the README. The project has a blog post explaining its internals, which is useful for understanding performance. Overall, the license is favorable, but the beta status means you should budget time for maintenance.

Editorial conclusion

Adopt Yazi if you are a terminal-centric user who wants a fast, scriptable file manager with image previews and plugin extensibility, and you can tolerate a public beta that is under heavy development with breaking changes. Do not adopt it if you need a stable, long-term tool with a mature plugin ecosystem or if you rely on a terminal that lacks support for the listed image protocols. Before adopting, verify that your terminal is in the supported image preview table and that you are comfortable with the Lua plugin APIs, which may shift between releases. The project is MIT-licensed, so you can fork it if changes break your workflow, but you must track the nightly releases for fixes and features.

Official sources

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