Getting started

Introduction

Yazi is a fast terminal file manager written in Rust. It previews images, video, PDFs, and archives, and is configured with three TOML files.

Install

# Arch Linux
sudo pacman -S yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide

# macOS
brew install yazi ffmpeg sevenzip jq poppler fd ripgrep fzf zoxide

# Debian/Ubuntu: use the official APT repo
curl -fsSL https://yazi-rs.github.io/builds/yazi-keyring.gpg \
  | sudo tee /usr/share/keyrings/yazi-keyring.gpg >/dev/null
printf '%s %s\n' \
  'deb [signed-by=/usr/share/keyrings/yazi-keyring.gpg]' \
  'https://yazi-rs.github.io/builds/ stable main' \
  | sudo tee /etc/apt/sources.list.d/yazi.list
sudo apt update && sudo apt install yazi

file(1) is required; ffmpeg, 7z, jq, poppler, fd, rg, fzf, and zoxide unlock extra previews and searches. A Nerd Font is recommended.

See: Installation

Start

yazi                  # current directory
yazi ~/Downloads      # start elsewhere
yazi a.txt b.txt      # preset the selection
yazi --version

q quits and Q quits without writing the cwd file. ~ or F1 opens help.

See: Quick start

Shell wrapper

function y() {
	local tmp cwd; tmp="$(mktemp -t "yazi-cwd.XXXXXX")"
	command yazi "$@" --cwd-file="$tmp"
	IFS= read -r -d '' cwd < "$tmp"
	[ "$cwd" != "$PWD" ] && [ -d "$cwd" ] && builtin cd -- "$cwd"
	command rm -f -- "$tmp"
}

Add it to your shell rc and run y instead of yazi; the parent shell then follows Yazi's last directory. Fish, Nushell, PowerShell, and other ports are in the docs.

See: Shell wrapper

Cursor

KeyAction
k / jUp / down
gg / GTop / bottom
<C-u> / <C-d>Half page up / down
<C-b> / <C-f>Full page up / down
K / JSeek preview up / down

Arrow keys work too. J and K scroll the preview without moving the cursor.

See: cursor motion

Directories

KeyAction
l / hEnter child / leave to parent
H / LBack / forward in history
ghHome
gc~/.config
gd~/Downloads
g<Space>Go to a typed path
z / ZJump with fzf / zoxide

z needs fzf; Z needs fzf and zoxide.

See: leave

Tabs

KeyAction
t tNew tab in current directory
1 - 9Switch to tab N
[ / ]Previous / next tab
{ / }Swap tab left / right
<C-c>Close the current tab

Closing the last tab quits Yazi.

See: tab_create

Files

Open

KeyAction
<Enter> / oOpen with the default opener
O / <S-Enter>Choose an opener
;Run a shell command
:Run a shell command, blocking

O lists every opener the matching [open] rule allows. ; and : run in the current directory.

See: open

Yank and paste

KeyAction
yYank (copy)
xYank (cut)
pPaste
PPaste, overwriting existing files
Y / XCancel the yank

Selection

KeyAction
<Space>Toggle selection
<C-a> / <C-r>Select all / invert selection
v / VVisual mode

y copies and x cuts; both act on the selection, or on the hovered file when nothing is selected.

See: yank

Create and rename

KeyAction
aCreate a file (/ suffix: directory)
ABulk create, one path per line
rRename, cursor before extension

A trailing / makes a directory. A opens a text buffer, then creates every path in it. r renames the selection together when several files are marked.

See: create

Delete and copy paths

KeyAction
dMove to the trash
DDelete permanently
ccCopy the path
cdCopy the directory path
cfCopy the filename
cnCopy the filename without extension

d moves files to the trash; D skips it.

See: remove

Hidden files and sorting

KeyAction
.Toggle hidden files

Sorting

KeyAction
,m / ,MSort by modified time
,b / ,BSort by birth time
,a / ,ASort alphabetically
,n / ,NSort naturally
,e / ,ESort by extension
,s / ,SSort by size
,rSort randomly

Uppercase variants reverse the order. Defaults live under [mgr] in yazi.toml.

See: sort

Find and filter

Find

KeyAction
/Find the next match
?Find the previous match
n / NNext / previous found
<Esc>Cancel find

Find matches names in the current directory as you type.

See: find

Filter

KeyAction
fFilter the file list
<Esc>Clear the filter

The filter narrows the listing until you clear it.

See: filter

KeyAction
sSearch names with fd
SSearch contents with ripgrep
<C-s>Cancel the search

Search covers subdirectories and needs fd or rg on PATH.

See: search

Previews

Spot

KeyAction
<Tab>Toggle file details
<Esc>Close the spot

Spot shows the MIME type, size, and permissions — useful when writing [open] rules.

See: spot

Image preview

# tmux.conf: let image protocols through
set -g allow-passthrough on
set -ga update-environment TERM
set -ga update-environment TERM_PROGRAM

Yazi picks kitty, iTerm2, WezTerm, Sixel, Überzug++, or Chafa automatically. Outside a supported terminal, install ueberzugpp or chafa. Code, JSON, folders, PDFs, and archives preview through built-in plugins.

See: image preview

Preview settings

# ~/.config/yazi/yazi.toml
[preview]
max_width  = 1000
max_height = 1000
wrap       = "yes"
tab_size   = 2

Images render at the smaller of these limits and the terminal size. Run ya cache clear after changing the image limits.

See: preview

CLI and integration

Flags

yazi --chooser-file=/tmp/picked   # write opened paths, then quit
yazi --cwd-file=/tmp/cwd          # write the cwd on exit
yazi --local-events=hover,cd      # stream local events to stdout
yazi --client-id=12345            # stable ID for ya emit-to

Positional arguments set the starting entries.

See: yazi --help

Chooser file

tmp="$(mktemp)"
yazi --chooser-file="$tmp"
cat "$tmp"          # one selected path per line
rm -f "$tmp"

With --chooser-file, Enter or o writes the selected paths and exits, so shells and editors can use Yazi as a file picker.

See: Helix picker example

Editor

# ~/.config/yazi/yazi.toml
[[opener.edit]]
run   = "$EDITOR %s"
block = true
for   = "unix"

[[open.prepend_rules]]
mime = "text/*"
use  = "edit"

block = true hands the terminal to the editor and waits. %s expands to the selected paths; for limits the opener to an OS.

See: opener

Configuration

Config files

FilePurpose
yazi.tomlGeneral settings and openers
keymap.tomlKeybindings
theme.tomlColors and flavors
init.luaPlugin setup

Files live in ~/.config/yazi/ (%AppData%\yazi\config\ on Windows). Set YAZI_CONFIG_HOME to use another directory.

See: configuration

yazi.toml

# ~/.config/yazi/yazi.toml
[mgr]
show_hidden = true
sort_by     = "natural"
linemode    = "size"

[preview]
max_width   = 1000

Only the keys you set override the defaults; the shipped file is the full reference.

See: yazi.toml

keymap.toml

# ~/.config/yazi/keymap.toml
[[mgr.prepend_keymap]]
on   = [ "g", "d" ]
run  = "cd ~/Downloads"
desc = "Go to Downloads"

[[mgr.append_keymap]]
on   = "T"
run  = "tab_create --current"
desc = "New tab here"

prepend_keymap wins over the defaults, append_keymap loses to them, and keymap replaces the layer.

See: keymap.toml

theme.toml

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

[mgr]
cwd = { fg = "#89b4fa" }

Install flavors with ya pkg add yazi-rs/flavors:catppuccin-mocha. Colors take hex values or named colors.

See: theme.toml

Openers

# ~/.config/yazi/yazi.toml
[opener]
edit = [
	{ run = "$EDITOR %s", block = true, for = "unix" },
	{ run = "code --wait %s", block = true },
]
play = [ { run = "mpv %s", orphan = true } ]

[open]
prepend_rules = [
	{ mime = "text/*", use = "edit" },
	{ mime = "video/*", use = "play" },
]

%s expands to all selected paths, %s1 to the first. block waits for the program; orphan keeps it running after Yazi exits.

See: opener

Plugins

Package manager

ya pkg add yazi-rs/plugins:git   # install a plugin
ya pkg add owner/my-plugin       # install a whole repo
ya pkg list                      # show installed packages
ya pkg install                   # restore from package.toml
ya pkg upgrade                   # update all packages

ya pkg clones packages into plugins/ or flavors/ and records them in package.toml.

See: package manager

Actions and events

ya emit cd /tmp                # run an action in Yazi
ya emit reveal /tmp/foo
ya pub my-event --str hello    # publish a DDS message
ya env                         # print environment info

ya emit targets the current instance through $YAZI_ID; ya emit-to takes an explicit ID.

See: ya emit

Plugin config

# ~/.config/yazi/yazi.toml
[plugin]
prepend_previewers = [
	{ mime = "image/heic", run = "heic" },
]
prepend_preloaders = [
	{ mime = "image/heic", run = "heic" },
]

Previewers draw a file type; preloaders cache it. Initialize plugins in init.lua.

See: plugin rules

0 Comments for this cheatsheet. Write yours!