How to Use Yazi: The Beginner's Guide (First Launch, the Shell-Wrapper Lesson, the Config Trio, and Previews)

CodexFuse Team · 2026-11-07T06:14:27.742Z · 20 min read min read

How Do I Use Yazi?

Learning how to use yazi takes seven moves: install it on your system, add the shell wrapper so quitting changes your directory, launch it, learn the vim keys, set up previews, shape the three config files, and add plugins with ya pkg. A yazi file manager is a terminal app written in Rust that shows your files in three panes, previews images and documents without opening them, and runs every file operation in the background so the interface never freezes. This yazi tutorial follows the official Yazi documentation and the project changelog, with every fact checked as of November 2026, and it is pinned to the current release, v26.9.1.

CodexFuse offers no Yazi tool, so this guide teaches the real program on your own machine, not a web version of it. No Facebook promotion applies to this guide. Yazi is the terminal-file-manager lane opener in our dev-tools cluster, and the charm-ecosystem sibling is covered in our Gum beginner guide, which you should read if you want to build terminal prompts inside scripts instead of managing files.

1. Install Yazi with your package manager, plus the optional tools that power previews.
2. Add the y() shell wrapper to your shell config so quitting Yazi moves your shell.
3. Launch Yazi with y and learn the three panes.
4. Navigate with j, k, h, and l, and select files with Space.
5. Preview images, PDFs, and videos in the right pane.
6. Shape yazi.toml, keymap.toml, and theme.toml to your taste.
7. Add plugins with ya pkg when you want more, starting with git.

What Is Yazi, Exactly?

Yazi is a terminal file manager written in Rust, built on fully async input and output, and its name means duck in Chinese. Every listing, preview, and file operation runs on background threads, so opening a directory with ten thousand files never freezes the interface the way a synchronous file manager can. The project calls itself a public beta that works as a daily driver, and it has gathered 43,270 GitHub stars in the 1,218 days since it was created on 8 July 2023.

With 43,270 stars against 1,059 forks, Yazi averages 40.86 stars per fork, and its 64 open issues work out to 0.15 per 100 stars. Only 17 days passed between v26.8.15 and v26.9.1.

The version number tells you how fast this project moves. The 25.x line ended at v25.12.29 in December 2025, and the current era is 26.x, so any guide that still talks about the 25.x era is out of date. The 2026 releases ran v26.1.4 in January, v26.5.6 in May, v26.8.15 in August, and v26.9.1 in September, and v26.9.1 is a bugfix release, which means the feature set of v26.8.15 is the one beginners actually meet.

How Do I Install Yazi?

A yazi install starts with your system package manager, and the route depends on your operating system. The official docs list Arch, Nix, Homebrew, MacPorts, Debian and Ubuntu, Fedora, Windows, Snap, Flatpak, MSYS2, Mise, and Cargo, plus official GNU and musl binaries from the GitHub releases page. The only required dependency is the file command, which detects MIME types, and everything else is optional.

brew install yazi ffmpeg sevenzip jq poppler fd ripgrep fzf zoxide resvg imagemagick font-symbols-only-nerd-font
sudo pacman -S yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick
sudo apt update
sudo apt install yazi
winget install sxyazi.yazi

The official APT repository for Debian and Ubuntu is new in v26.8.15, and it is the detail that dates most older guides. Starmorph, the most complete independent guide, was published on 20 March 2026, 232 days ago, and it still says there is no official apt package, because the repository did not exist yet. The same guide says Yazi has 33,000 stars, while the live count is now 43,270, which is one more reason to check the version before trusting any install page.

The optional dependencies are the previews, so install the ones that match the files you open. The docs map each tool to the feature it unlocks, and a missing tool simply means a blank preview pane for that file type, not an error.

Two names in older guides are stale and should not be installed. The entry-era guides tell you to install ffmpegthumbnailer and unar, but the current official docs use ffmpeg for video thumbnails and 7-Zip for archives instead. Most distro packages are community maintained and may lag the latest release, so check the version with yazi --version after installing and compare it with v26.9.1.

Why Does Quitting Yazi Not Change My Directory?

The yazi shell wrapper is a small function that solves the number one beginner frustration, and it is the lesson most first-time users miss. A subprocess cannot change its parent shell's working directory, so plain yazi followed by q leaves your shell exactly where it started, no matter how far you browsed inside Yazi. The fix is a wrapper function that asks Yazi to write your final directory to a temporary file, then reads that file and changes directory for you.

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

The wrapper is y(), not yy(), and that single letter is the name every source uses, from the official docs to the oldest guides. Add the function to your .zshrc or .bashrc, restart the shell, and launch Yazi with y instead of yazi from then on. Quitting with q writes the directory and moves your shell there, while quitting with Q leaves your shell where it was, and the official docs ship variants of the same function for Fish, Nushell, PowerShell, and several other shells.

How Do I Navigate Yazi with Vim Keys?

The yazi keybindings follow vim, so anyone who knows vim motions already knows most of Yazi. The layout is three panes: the parent directory on the left, the current directory in the middle, and a preview of the hovered file on the right. Move with j and k, enter a directory or open a file with l, go back to the parent with h, and press Space to select a file without moving the cursor.

Yazi lives inside your terminal, so pair it with a multiplexer that keeps the session alive, and our tmux beginner guide shows how to run Yazi inside a session you can detach and reattach. Tabs keep several directories open at once: press t, then t, to create a new tab, press 1 through 9 to switch to a tab, and use the bracket keys to move between tabs. Tab creation changed to the t then t chord in v26.5.6, 186 days ago, so any guide that tells you to press a single t for a new tab is teaching the old binding.

The trash bin arrived in v26.8.15, 84 days ago, and it changes how deletion works. Pressing d now moves files to the trash instead of deleting them, pressing D deletes permanently, and pressing g, then t, opens the trash view. File operations run as background tasks with live progress, and the task manager at w lets you watch a big copy finish or cancel it with x.

How Do Previews Work in Yazi?

The yazi previews system picks the best image protocol automatically, using your terminal type and session to decide. Built-in protocols cover Kitty graphics, Sixel, and iTerm2 inline images, which together reach kitty, Ghostty, WezTerm, Warp, foot, and Windows Terminal, while Uberzug++ and Chafa serve as fallbacks where no native protocol exists. Text and code preview with syntax highlighting, and the same right pane shows PDFs, video thumbnails, archive trees, JSON, SVG files, and directory listings.

Alacritty has no native image protocol, so it falls back to Uberzug++ on X11 and Wayland and to Chafa everywhere else, which is the single most common reason a new user sees no images. Inside tmux, image previews need three lines in tmux.conf, allow-passthrough turned on, the TERM and TERM_PROGRAM variables passed through, and a full tmux kill-server restart. Diagnose any preview problem with ya env, which reports the terminal emulator, the image adapter, and the SSH mode, and with yazi --debug when you need the detail.

Yazi previews markdown files in the pane, and if you want a dedicated markdown reader, our Glow beginner guide covers the terminal reader built for that job. The preview size is the smaller of your max_width and max_height settings and the terminal pixel size, so a narrow terminal shows a smaller image even when the file is large.

How Do I Configure Yazi?

The yazi config lives in three files inside ~/.config/yazi on Unix systems, or %AppData%\yazi\config on Windows, and each file owns one layer. The yazi.toml file holds general settings, keymap.toml holds keybindings, and theme.toml holds colors, while a fourth file, init.lua, runs at startup and is where plugin setup lives. The defaults ship inside the release, so copy only the section you want to change instead of copying a whole preset file into your config directory.

# ~/.config/yazi/yazi.toml
[mgr]
show_hidden = true
sort_by = "natural"
sort_dir_first = true
scrolloff = 5

[preview]
wrap = "no"
tab_size = 2

# ~/.config/yazi/keymap.toml
[mgr]
prepend_keymap = [
  { on = ["g", "r"], run = "cd ~/repos", desc = "Go to repos" },
]

# ~/.config/yazi/theme.toml
[flavor]
dark = "catppuccin-mocha"
light = "catppuccin-latte"

Keybindings extend without overriding the defaults through prepend_keymap and append_keymap, and the same prepend and append pattern works for opener, icon, previewer, and preloader rules. The YAZI_CONFIG_HOME environment variable points Yazi at a different config directory when you want one, which is handy for testing a new setup without touching your working one. If configuring Yazi makes you want to build your own terminal app, our Ratatui beginner guide teaches the Rust framework for that job, and its event loop is the closest cousin to the one Yazi runs.

How Do I Add Plugins with ya pkg?

The ya pkg lesson starts with a correction, because ya pack is dead in 26.x and its commands no longer work. Older guides, including the Josean field leader from 21 December 2024, 686 days ago, teach ya pack to install flavors, and the TecMint guide from 17 July 2026, 113 days ago, is the one that documents the migration to ya pkg in print. The current command is ya pkg add with an owner, repo, and plugin name, and packages are tracked in package.toml, which you can version-control and replay on a fresh machine with ya pkg install.

ya pkg add yazi-rs/plugins:git
ya pkg add yazi-rs/plugins:smart-enter
ya pkg add yazi-rs/plugins:full-border
ya pkg add yazi-rs/flavors:catppuccin-mocha
ya pkg list
ya pkg upgrade

Plugins are Lua scripts, and the language moved to Lua 5.5 in v26.5.6, so a plugin written for Lua 5.4 may need a check before you trust it. The official plugins monorepo, yazi-rs/plugins, holds 629 stars and 22 plugin directories today, and the git plugin needs two pieces of wiring: a require line in init.lua and fetcher entries in yazi.toml. The git plugin shows status inline, and if you want the version-control side first, our Git beginner guide covers the tool it watches, from first commit to branching.

require("git"):setup { order = 1500 }
require("full-border"):setup()

Flavors are themes installed the same way, and the catppuccin-mocha flavor is the one most guides use as the example, set in theme.toml under a flavor section with dark and light names. The ya version must match the yazi version, or package commands can fail in confusing ways, and ya pkg upgrade updates every installed package at once.

Yazi vs Ranger: Which Terminal File Manager Should I Pick?

Yazi vs ranger is the comparison most readers ask about, because ranger is the veteran every terminal user has heard of and Yazi is the modern challenger. The differences are verifiable and architectural: Yazi is written in Rust with fully async input and output, while ranger is written in Python with synchronous input and output, and that single choice shapes everything else. Yazi previews images natively through Kitty, Sixel, and iTerm2 protocols, while ranger previews images only through Uberzug with manual setup, and Yazi extends through Lua plugins and the ya pkg manager, while ranger extends through Python scripts with no built-in package manager.

Yazi holds 25,820 more stars than ranger, or 2.48 times as many, and ranger holds 833 more open issues, which fits a 17-year-old project with a long tail of reports. Ranger is still maintained, with its last push on 9 September 2026, so the choice is not between a live project and a dead one. No measured speed benchmark exists for the two, so treat the speed difference as architectural, not as a number, and pick Yazi when you want native previews and a plugin manager, or ranger when you want the mature Python tool with a decade of configuration examples.

What Are the 7 Mistakes Every Yazi Beginner Makes?

from datetime import date
today = date(2026, 11, 7)
created = date(2023, 7, 8)
first_release = date(2023, 7, 19)
v2691 = date(2026, 9, 1)
v26815 = date(2026, 8, 15)
v2656 = date(2026, 5, 5)
josean = date(2024, 12, 21)
starmorph = date(2026, 3, 20)
tecmint = date(2026, 7, 17)
mnishiguchi = date(2025, 3, 18)
ranger_created = date(2009, 6, 4)
stars = 43270
forks = 1059
issues = 64
ranger_stars = 17450
ranger_issues = 897
print("repo age days:", (today - created).days)
print("repo age years:", round((today - created).days / 365.25, 2))
print("first release age days:", (today - first_release).days)
print("stars per fork:", round(stars / forks, 2))
print("open issues per 100 stars:", round(issues / stars * 100, 2))
print("v26.9.1 age days:", (today - v2691).days)
print("v26.8.15 age days:", (today - v26815).days)
print("v26.5.6 age days:", (today - v2656).days)
print("days between v26.8.15 and v26.9.1:", (v2691 - v26815).days)
print("josean age days:", (today - josean).days)
print("starmorph age days:", (today - starmorph).days)
print("tecmint age days:", (today - tecmint).days)
print("mnishiguchi age days:", (today - mnishiguchi).days)
print("ranger age days:", (today - ranger_created).days)
print("ranger age years:", round((today - ranger_created).days / 365.25, 2))
print("yazi stars minus ranger stars:", stars - ranger_stars)
print("yazi stars divided by ranger stars:", round(stars / ranger_stars, 2))
print("ranger open issues minus yazi open issues:", ranger_issues - issues)
print("ranger open issues per 100 stars:", round(ranger_issues / ranger_stars * 100, 2))

Sources

The facts in this guide come from the official Yazi documentation on yazi-rs.github.io, including the installation page, the quick-start page, the configuration overview, and the image-preview page, all fetched on 7 November 2026, plus the project changelog on the main branch, which pins the v26.8.15 feature set and the v26.9.1 bugfix release. The repository figures come from the GitHub API for sxyazi/yazi, yazi-rs/plugins, and ranger/ranger, fetched the same day, and they are snapshots as of 7 November 2026, not permanent totals.

The field guides are the TecMint guide from 17 July 2026, which is the freshest full independent guide and the one that documents the ya pack to ya pkg migration, the Starmorph guide from 20 March 2026, which is the most complete independent guide and is now partly stale on tabs, Lua, stars, and the APT repository, and the Josean guide from 21 December 2024, which is the field leader frozen at v0.4.1. The comparison framing draws on the deska.dev 2026 comparison and the Linuxize roundup updated around 12 October 2026, which tested Yazi 26.9.1 against ranger 1.9.4, lf 38, nnn 5.1, and Midnight Commander 4.8.33. The mnishiguchi dev.to piece from 18 March 2025, 599 days ago, covers the y-to-z navigation workflow with zoxide and fzf rather than a full guide.

Every number in the tables and the computed block was produced by running the Python script above on 7 November 2026, and every version, date, and command was checked against the live sources this run. No commands in this guide were executed in a live testbed, so every command shown is documented syntax from the official docs, and no benchmark number appears anywhere, because no measured comparison of Yazi and ranger was found from a verifiable source. Features on the main branch that have not shipped in a stable release, including file compression, rclone integration, and Windows MSI installers, are not presented as shipped anywhere in this guide.

Frequently Asked Questions

Is Yazi free to use?

Yes, Yazi is free and open source under the MIT license, with no paid tier and no locked features, and the plugins and flavors in the official repositories are free as well. You download it, install it, and use it on as many machines as you like, and the only costs are the optional tools you choose to add for previews. The project accepts contributions on GitHub, where it holds 43,270 stars as of 7 November 2026.

Does Yazi work on Windows?

Yes, Yazi installs on Windows through Scoop or WinGet, and its configuration lives in %AppData%\yazi\config instead of ~/.config/yazi. Image previews work only in WezTerm nightly, Windows Terminal, and Bobcat v0.9.0, and the file command needs Git for Windows, pointed at through the YAZI_FILE_ONE environment variable. The docs warn against the Scoop and Chocolatey builds of file, because they mishandle Unicode filenames.

Why do my image previews show nothing?

The most common cause is a terminal with no native image protocol, and Alacritty is the usual case, because it falls back to Uberzug++ or Chafa. Run ya env to see which adapter Yazi detected, then check that the matching tool is installed, and remember that tmux needs allow-passthrough plus a full kill-server restart before previews appear. A missing optional tool gives a blank pane for that file type, so install ffmpeg, 7-Zip, jq, and poppler before blaming the terminal.

How do I change my directory on exit?

Add the y() shell wrapper function to your shell config, then launch Yazi with y instead of yazi, and quitting with q moves your shell into the directory you were browsing. Quitting with Q deliberately skips the move, which is useful when you only wanted a quick look, and the wrapper works because it reads the directory Yazi writes to a temporary file through --cwd-file. The official docs ship the same function for Fish, Nushell, PowerShell, and several other shells.

Is Yazi better than ranger?

Yazi is the better pick when you want native image previews, async input and output, and a built-in plugin manager, while ranger is the better pick when you want a mature Python tool with seventeen years of configuration examples. Yazi holds 2.48 times as many GitHub stars, but stars are popularity, not proof of speed, and no measured benchmark compares the two. Try Yazi for a week on your real workflow, keep ranger installed beside it, and keep the one that fits your hands.