Skip to content
Get packs

Guide · Open source

How to use Yazi: install, navigate and preview files

Updated · written with AI from the project's own documentation and checked against our catalogue data

Yazi is a file manager that runs inside a terminal window, so you browse, copy, move and preview files from the keyboard. This guide explains what it does, what to install alongside it, and how to get comfortable with its main features. It is aimed at people who already spend time in a terminal and want a faster way to move around folders.

Yazisxyazi/yazi · ★ 43.2k · MIT

Quick start

  1. 1Confirm you have a terminal that suits Yazi. Check that your terminal is one you use daily and, if you want images, that it appears in the image preview list.
  2. 2Get Yazi. Follow the download instructions on the official documentation site for your operating system. The README's clone command points to the source repository.
  3. 3Install optional preview helpers. Add Überzug++ on X11 or Wayland, or Chafa 1.16.0 or newer for ASCII fallback previews, if your terminal needs them.
  4. 4Launch Yazi and browse. Open Yazi in a terminal and move through your folders with the keyboard.
  5. 5Preview and select files. Use previews to check contents, then select one or more items, including across directories.
  6. 6Try a bulk operation. Use bulk rename or archive extraction on a test folder to learn how they behave.
  7. 7Add plugins when needed. Use the package manager to install a plugin or theme, and pin a version if you need stability.

What Yazi is and who it suits

Yazi (the name means "duck") is a terminal file manager written in Rust. The project describes it as based on non-blocking async I/O and aimed at an efficient, user-friendly and customizable file management experience.

It is a good fit if you already work in a terminal and want to browse folders quickly. It is not a good fit if you want a graphical window with drag-and-drop-first workflows and no terminal use, since Yazi is terminal-only.

  • Good fit: terminal users, developers who want previews and Git status, people who want themes and plugins.
  • Poor fit: people who avoid the terminal entirely, and people who need a tool that never changes.

Install Yazi from the download page

The project's install method is to download the app. The README gives a clone command for the source repository, and the full installation instructions are on the project's documentation site, which you should follow for your operating system.

Two optional tools improve image previews. Überzug++ is used for image preview on X11 or Wayland. Chafa, version 1.16.0 or newer, provides the ASCII fallback preview.

  • Optional: Überzug++ for image preview on X11 or Wayland.
  • Optional: Chafa 1.16.0 or newer for the ASCII fallback preview.
git clone https://github.com/sxyazi/yazi.git

Check whether your terminal supports image previews

Yazi has built-in support for several image protocols. The README lists kitty (0.28.0 or newer), iTerm2, WezTerm, Konsole, foot, Ghostty, Windows Terminal (v1.22.10352.0 or newer), Warp on macOS and Linux, Tabby, VSCode, Rio (0.3.9 or newer), Black Box and Bobcat as built-in supported terminals.

If your terminal is not on that list, you can still use Yazi. Without a supported protocol, or without Überzug++ on X11 or Wayland, you get fallback previews, and installing Chafa gives you an ASCII-art preview instead.

Learn the core workflow: browse, select, copy and move

Yazi is built around keyboard navigation. You move through folders, open a file or directory, and preview its contents without leaving the window. The README describes multi-tab support, cross-directory selection and a visual mode for selecting several items.

Bulk operations are part of the core feature set. The README lists bulk rename and create, archive extraction, a file chooser and a trash bin. For exact key bindings, check the official documentation linked below rather than relying on memory.

  • Use multiple tabs to keep several folders open at once.
  • Select items across different directories before acting on them.
  • Use visual mode to select a range of files.
  • Use bulk rename to change many file names together.
  • Extract archives directly from Yazi.

Extend Yazi with integrations and plugins

Yazi integrates with ripgrep, fd, fzf, zoxide and Rclone. Its plugin system is written in Lua and includes UI plugins, functional plugins and custom previewers. A package manager installs plugins and themes with one command, keeps them updated, or pins them to a specific version.

Git status is available through the git.yazi plugin, and remote access through the virtual filesystem feature. The README notes that the project is in heavy development and expects breaking changes, so pin plugin and app versions if you rely on them.

  • Integrations: ripgrep, fd, fzf, zoxide, Rclone.
  • Plugin system: Lua-based, with a package manager for plugins and themes.
  • Virtual filesystem: remote file management and custom VFS providers.

Know the project status before relying on it

The README describes Yazi as a public beta that can be used as a daily driver, while also stating that it is in heavy development and that breaking changes are expected. Plan for updates that change behaviour.

For usage details, the README points to the documentation site at yazi-rs.github.io. Community discussion happens on a Discord server (mainly English) and a Telegram group (mainly Chinese).

What people use it for

  • Browsing project folders over SSH from a terminal without a graphical desktop.
  • Previewing images, PDFs, videos, archives and code before opening them.
  • Renaming many files at once with bulk rename.
  • Checking Git status while navigating a repository, using the git.yazi plugin.
  • Browsing remote files through the virtual filesystem or Rclone integration.

Frequently asked questions

Is Yazi free and what is its licence?

Yazi is MIT-licensed, according to the README, and the LICENSE file in the repository has the full terms. The source is on GitHub under the sxyazi account.

What do I need to install Yazi?

The install method is to download the app. For better image previews, the README lists optional Überzug++ for X11 or Wayland and Chafa 1.16.0 or newer for the ASCII fallback.

Why does Yazi show only basic previews for images?

Image previews depend on your terminal supporting an image protocol. If your terminal is not in the supported list, you get fallback previews unless you install Chafa, or Überzug++ on X11 or Wayland.

Is Yazi stable enough for daily use?

The README calls it a public beta that can be used as a daily driver, but also says it is in heavy development and expects breaking changes. Pin versions if stability matters to you.

How does Yazi compare to ranger, nnn, lf or Midnight Commander?

Yazi is in the same family as ranger, nnn, lf and Midnight Commander, all terminal file managers. This page does not benchmark them, so compare features and fit for your workflow on the projects' own pages.

Can I use Yazi on a remote machine?

The README lists a virtual filesystem for remote file management and integration with Rclone. Check the official documentation for setup details.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Yazi suits people who already work in a terminal and want fast browsing, previews, bulk operations and a Lua plugin system, and it is free under the MIT licence. Pick something else if you want a graphical file manager with drag-and-drop-first workflows, or if you need a tool that will not change between versions, since the project says breaking changes are expected.

Install options & downloads