Terminal GuideTerminal Guide
yazi icon

yazi

File Managers
macOSLinuxWindows
Rust

Blazing fast Rust terminal file manager with async I/O.

Official Website

Features

Async I/OImage PreviewPlugin SystemTabs

Installation

Homebrew
brew install yazi
Pacman (Arch)
pacman -S yazi
Cargo (Rust)
cargo install yazi-fm

Why use yazi?

Ultra Fast with Async I/O

Fully async architecture with Rust + Tokio. File listing, preview generation, and copy all run async without blocking the UI.

Rich Preview

Support diverse previews: images, video thumbnails, PDFs, archive contents. Multiple image protocols: Sixel, Kitty Graphics Protocol, iTerm2, and more.

Tab Support

Open multiple tabs to work with different directories simultaneously. Easy file operations between tabs.

Lua Plugins

Plugin system with Lua for advanced customization. Rich collection of community plugins available.

Installation

Installation Commands
# Homebrew (macOS/Linux)
brew install yazi ffmpegthumbnailer unar jq poppler fd ripgrep fzf zoxide

# Cargo (Rust)
cargo install yazi-fm yazi-cli

# Pacman (Arch Linux)
sudo pacman -S yazi ffmpegthumbnailer unarchiver jq poppler fd ripgrep fzf zoxide

# Scoop (Windows)
scoop install yazi

# Nix
nix-env -iA nixpkgs.yazi

For full features, also install optional dependencies: ffmpegthumbnailer, unar, jq, poppler, etc.

Screen Layout

yazi uses a three-pane layout similar to ranger but with async fast preview generation.

┌─ yazi ─────────────────────────────────────────────────────────┐
│ ~/.config/yazi                                                 │
│                                                                │
│  ..                                                           │
│  flavors/                                                     │
│  plugins/                                                     │
│  init.lua                           -- Lua init file          │
│> keymap.toml                        -- Keymap configuration   │
│  theme.toml                         -- Theme configuration    │
│  yazi.toml                          -- Main configuration     │
│                                                                │
│────────────────────────────────────────────────────────────────│
│ [[manager.prepend_keymap]]                                     │
│ on = ["g", "h"]                                                │
│ run = "cd ~"                                                   │
│ desc = "Go to home directory"                                  │
│                                                                │
│ [[manager.prepend_keymap]]                                     │
│ on = ["g", "c"]                                                │
│ ...                                                            │
├────────────────────────────────────────────────────────────────┤
│ ~/.config/yazi  5 items  [1/5]            keymap.toml  1.2KB   │
└────────────────────────────────────────────────────────────────┘

Basic Operations

KeyAction
j / kMove up/down
h / lParent directory / Enter directory
EnterOpen file
gg / GGo to start / end
/Search
.Toggle hidden files
tOpen new tab
1-9Switch to tab 1-9
qQuit

File Operations

KeyAction
SpaceSelect/deselect file
vVisual selection mode
VSelect all
yCopy (yank)
xCut
pPaste
PPaste (overwrite)
dDelete
rRename
aCreate new file/directory

Task Management

yazi manages file operations as async tasks. Large file copies run without blocking the UI.

KeyAction
wOpen task manager
x (task screen)Cancel task

Configuration & Customization

Configuration files are placed in ~/.config/yazi/. Written in TOML format.

~/.config/yazi/yazi.toml
# ~/.config/yazi/yazi.toml

[manager]
ratio = [1, 4, 3]          # Panel ratio
sort_by = "natural"        # Sort method
sort_sensitive = false     # Case sensitive
sort_reverse = false       # Reverse order
sort_dir_first = true      # Show directories first
linemode = "size"          # Line mode (size, mtime, permissions, none)
show_hidden = false        # Show hidden files
show_symlink = true        # Show symbolic links

[preview]
tab_size = 2               # Tab size
max_width = 600            # Maximum width
max_height = 900           # Maximum height
cache_dir = ""             # Cache directory
image_filter = "triangle"  # Image filter
image_quality = 75         # Image quality
sixel_fraction = 15        # Sixel fraction

[opener]
edit = [
  { run = '$EDITOR "$@"', block = true, for = "unix" },
  { run = 'code %*', orphan = true, for = "windows" },
]
open = [
  { run = 'xdg-open "$@"', desc = "Open", for = "linux" },
  { run = 'open "$@"', desc = "Open", for = "macos" },
  { run = 'start "" "%1"', orphan = true, for = "windows" },
]
reveal = [
  { run = 'open -R "$1"', desc = "Reveal in Finder", for = "macos" },
  { run = 'nautilus --select "$@"', desc = "Reveal in Nautilus", for = "linux" },
]

Keymap Configuration

~/.config/yazi/keymap.toml
# ~/.config/yazi/keymap.toml

[[manager.prepend_keymap]]
on = ["g", "h"]
run = "cd ~"
desc = "Go to home directory"

[[manager.prepend_keymap]]
on = ["g", "c"]
run = "cd ~/.config"
desc = "Go to config directory"

[[manager.prepend_keymap]]
on = ["g", "d"]
run = "cd ~/Downloads"
desc = "Go to downloads"

[[manager.prepend_keymap]]
on = ["<C-s>"]
run = "shell 'zsh' --block --confirm"
desc = "Open shell here"

[[manager.prepend_keymap]]
on = ["T"]
run = "shell 'trash-put -- "$@"' --confirm"
desc = "Move to trash"

[[manager.prepend_keymap]]
on = ["<C-n>"]
run = "create"
desc = "Create file or directory"

Theme Configuration

~/.config/yazi/theme.toml
# ~/.config/yazi/theme.toml

[manager]
cwd = { fg = "cyan" }
hovered = { fg = "black", bg = "lightblue" }
preview_hovered = { underline = true }

# Markers
marker_selected = { fg = "lightgreen", bg = "lightgreen" }
marker_copied = { fg = "lightyellow", bg = "lightyellow" }
marker_cut = { fg = "lightred", bg = "lightred" }

# Tabs
tab_active = { fg = "black", bg = "lightblue" }
tab_inactive = { fg = "white", bg = "darkgray" }

# Border
border_symbol = ""
border_style = { fg = "gray" }

[status]
separator_open = ""
separator_close = ""
separator_style = { fg = "darkgray", bg = "darkgray" }

[filetype]
rules = [
  { name = "*/", fg = "lightcyan", bold = true },
  { mime = "text/*", fg = "lightgreen" },
  { mime = "image/*", fg = "lightyellow" },
  { mime = "video/*", fg = "lightmagenta" },
  { mime = "audio/*", fg = "lightcyan" },
]

Plugins

yazi uses a Lua-based plugin system.

Plugin Installation
# Plugin installation
# yazi plugins are placed in ~/.config/yazi/plugins/

# Plugin example
git clone https://github.com/yazi-rs/plugins.git ~/.config/yazi/plugins

# Enable plugins in init.lua
# ~/.config/yazi/init.lua

require("full-border"):setup()
require("git"):setup()
require("starship"):setup()

# Popular plugins
# - full-border: Full border display
# - git: Git status display
# - starship: Starship prompt integration
# - max-preview: Maximum preview
# - compress: Archive creation

Popular Plugins

  • full-border - Full border display
  • git - Git status
  • starship - Starship integration
  • max-preview - Maximum preview

Flavors (Themes)

Place flavors in ~/.config/yazi/flavors/. Popular themes like Catppuccin and Tokyo Night available.

Shell Integration

Preserve current directory when yazi exits.

~/.bashrc or ~/.zshrc
# ~/.bashrc or ~/.zshrc

# Preserve directory when yazi exits
function y() {
  local tmp="$(mktemp -t "yazi-cwd.XXXXXX")"
  yazi "$@" --cwd-file="$tmp"
  if cwd="$(cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
    cd -- "$cwd"
  fi
  rm -f -- "$tmp"
}

# Or use shell function provided by yazi
# eval "$(yazi --cwd-file)" # for fish

Image Preview

yazi supports multiple image protocols. Automatically selects the optimal protocol for your terminal.

Supported Protocols

  • Kitty - Kitty Graphics Protocol
  • iTerm2 - iTerm2 Image Protocol
  • Sixel - Sixel Graphics
  • X11/Wayland - via ueberzugpp

Supported Preview Formats

  • Images (PNG, JPEG, GIF, WebP, SVG...)
  • Video thumbnails (ffmpegthumbnailer)
  • PDF (poppler)
  • Archive contents (unar)
  • Text (with syntax highlighting)

Tips

zoxide Integration

Press z to jump using zoxide. Quickly navigate to frequently used directories.

fzf Integration

Press f for fuzzy search with fzf. Quickly search and jump to files.

Bulk Operations

Press b to enter bulk rename mode, rename multiple files at once with your editor.

Clear Selection

Press Escape to clear all selections. Press u to clear copy/cut state.

Written by Dai AokiPublished: 2026-01-20

Related Articles

Explore More