Quick append

Note

Copy the ready-made files below into ~/.config/yazi/.

Adjust the directory paths in keymap.toml to match your own home folders.

~/.config/yazi/keymap.toml

# Custom g-prefix navigation. prepend_keymap = sits ahead of defaults.
# Kept defaults: g h (home), g c (~/.config), g d (Downloads), g t (/tmp), g g (top)

# --- major home dirs (plain cd: deterministic, fast) ---

[[mgr.prepend_keymap]]
on   = [ "g", "e" ]
run  = "cd ~/Desktop"
desc = "Go to Desktop"

[[mgr.prepend_keymap]]
on   = [ "g", "D" ]
run  = "cd ~/Documents"
desc = "Go to Documents"

[[mgr.prepend_keymap]]
on   = [ "g", "p" ]
run  = "cd ~/Pictures"
desc = "Go to Pictures"

[[mgr.prepend_keymap]]
on   = [ "g", "v" ]
run  = "cd ~/Videos"
desc = "Go to Videos"

[[mgr.prepend_keymap]]
on   = [ "g", "m" ]
run  = "cd ~/Music"
desc = "Go to Music"

[[mgr.prepend_keymap]]
on   = [ "g", "P" ]
run  = "cd ~/Public"
desc = "Go to Public"

[[mgr.prepend_keymap]]
on   = [ "g", "C" ]
run  = "cd ~/.config/yazi"
desc = "Go to yazi config"

# --- custom directories ---

[[mgr.prepend_keymap]]
on   = [ "g", "i" ]
run  = "cd ~/Installations"
desc = "Go to Installations"

[[mgr.prepend_keymap]]
on   = [ "g", "w" ]
run  = "cd ~/Projects"
desc = "Go to Projects"

[[mgr.prepend_keymap]]
on   = [ "g", "." ]
run  = "cd ~/.dotfiles"
desc = "Go to .dotfiles"

~/.config/yazi/theme.toml

# Partial override — only [which] is changed; everything else uses yazi defaults.
# Fixes the low-contrast g/which-key cheatsheet popup. Neutral dark palette.

[which]
cols = 3
# raised panel above the terminal background so the popup stands out
mask            = { bg = "#1e2228" }
# the highlighted next-key candidate(s) — gold accent, bold
cand            = { fg = "#dbbc7f", bold = true }
# remaining keys of a pending multi-key sequence — neutral grey
rest            = { fg = "#8a8f98" }
# the action description text — neutral off-white for readability
desc            = { fg = "#c5c8d0" }
separator       = "  "
separator_style = { fg = "#6b7280" }

~/.config/yazi/yazi.toml

[mgr]
# widen the preview pane (default [1, 4, 3])
ratio = [1, 2, 5]

[preview]
# raise render resolution in pixels (defaults 600 x 900)
max_width = 1200
max_height = 1600

~/.bashrc

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

Installation

Installing on your distro

Fedora (Terra)

With Terra enabled:

sudo dnf install yazi

Debian/Ubuntu

yazi is not in the stable apt repositories. The simplest portable method is via the Rust toolchain (works on any distro):

cargo install --locked yazi-fm yazi-cli

A community .deb repo also exists: Yazi installation docs.

Arch

sudo pacman -S yazi

Optional dependencies

These packages unlock previews, search, and jump features. Some of them are probably on your system already. Install whichever you need:

Package	Purpose
ffmpeg	Video thumbnails
7zip	Archive preview and extraction
jq	JSON preview
poppler	PDF preview
fd	File-name search
ripgrep	File-content search
fzf	Quick jump
zoxide	Jump to recent directories
resvg	SVG preview
imagemagick	Extra image formats (HEIC, JPEG XL)
nerd-fonts	Proper icon glyphs

Quick tips and usage

Essential keys

Key	Action
h / j / k / l or arrow keys	Navigate left / down / up / right
q	Quit and return to the original directory
Q	Quit without changing directory
.	Toggle hidden files
f	Filter entries in current directory
s	Search by file name (requires fd)
S	Search by file content (requires ripgrep)
t	Open a new tab
1 – 9	Switch to tab by number
[ / ]	Cycle between tabs

Check yazi's Quick Start for more.

Custom navigation shortcuts

These optional configs extend the g (go-to) shortcuts with quick jumps to common directories, plus a high-contrast cheatsheet popup. The theme.toml uses a neutral dark palette for the [which] popup.

Keys	Jumps to
g + D	~/Documents
g + p	~/Pictures
g + v	~/Videos
g + m	~/Music
g + e	~/Desktop
g + P	~/Public
g + C	~/.config/yazi
g + i	~/Installations
g + w	~/Projects
g + .	~/.dotfiles

Tips

g + i (~/Installations) and g + w (~/Projects) point to custom folders. Create them with mkdir ~/Installations ~/Projects, or edit those two paths in keymap.toml to suit your own setup.

The theme.toml below is a partial override — it changes only the [which] popup, so other elements are yazi default.

Custom config files

~/.config/yazi/keymap.toml

# Custom g-prefix navigation. prepend_keymap = sits ahead of defaults.
# Kept defaults: g h (home), g c (~/.config), g d (Downloads), g t (/tmp), g g (top)

# --- major home dirs (plain cd: deterministic, fast) ---

[[mgr.prepend_keymap]]
on   = [ "g", "e" ]
run  = "cd ~/Desktop"
desc = "Go to Desktop"

[[mgr.prepend_keymap]]
on   = [ "g", "D" ]
run  = "cd ~/Documents"
desc = "Go to Documents"

[[mgr.prepend_keymap]]
on   = [ "g", "p" ]
run  = "cd ~/Pictures"
desc = "Go to Pictures"

[[mgr.prepend_keymap]]
on   = [ "g", "v" ]
run  = "cd ~/Videos"
desc = "Go to Videos"

[[mgr.prepend_keymap]]
on   = [ "g", "m" ]
run  = "cd ~/Music"
desc = "Go to Music"

[[mgr.prepend_keymap]]
on   = [ "g", "P" ]
run  = "cd ~/Public"
desc = "Go to Public"

[[mgr.prepend_keymap]]
on   = [ "g", "C" ]
run  = "cd ~/.config/yazi"
desc = "Go to yazi config"

# --- custom directories ---

[[mgr.prepend_keymap]]
on   = [ "g", "i" ]
run  = "cd ~/Installations"
desc = "Go to Installations"

[[mgr.prepend_keymap]]
on   = [ "g", "w" ]
run  = "cd ~/Projects"
desc = "Go to Projects"

[[mgr.prepend_keymap]]
on   = [ "g", "." ]
run  = "cd ~/.dotfiles"
desc = "Go to .dotfiles"

~/.config/yazi/theme.toml

# Partial override — only [which] is changed; everything else uses yazi defaults.
# Fixes the low-contrast g/which-key cheatsheet popup. Neutral dark palette.

[which]
cols = 3
# raised panel above the terminal background so the popup stands out
mask            = { bg = "#1e2228" }
# the highlighted next-key candidate(s) — gold accent, bold
cand            = { fg = "#dbbc7f", bold = true }
# remaining keys of a pending multi-key sequence — neutral grey
rest            = { fg = "#8a8f98" }
# the action description text — neutral off-white for readability
desc            = { fg = "#c5c8d0" }
separator       = "  "
separator_style = { fg = "#6b7280" }

The y shell wrapper (cd-on-exit)

By default, running yazi directly won't change your shell's working directory when you quit. The y wrapper function fixes this — your shell follows yazi's last location on exit.

Add the following to ~/.bashrc (or your shell's equivalent), then run y instead of yazi:

~/.bashrc

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

After saving, reload your shell with source ~/.bashrc and use y.

Image previews

yazi supports in-terminal image rendering and auto-detects the best protocol for your terminal — no manual configuration needed.

For maximum compatibility, use Kitty

kitty is where the Kitty image protocol comes from, so yazi previews work natively with zero extra configuration. See the Kitty Terminal guide to get set up.

Resizing image previews

Image previews are configured in yazi's own ~/.config/yazi/yazi.toml — separate from your terminal's config. Two settings control how large a preview appears: the width of the preview pane and the maximum render resolution.

• ratio in the [mgr] section is the [parent, current, preview] column split (default [1, 4, 3]). Raise the third value to give previews more room, for example [1, 2, 5].
• max_width and max_height in the [preview] section cap the render resolution in pixels (defaults 600 and 900). Increase them for larger, sharper images.

~/.config/yazi/yazi.toml

[mgr]
# widen the preview pane (default [1, 4, 3])
ratio = [1, 2, 5]

[preview]
# raise render resolution in pixels (defaults 600 x 900)
max_width = 1200
max_height = 1600

yazi fits previews to the pane and re-renders automatically when you resize the window — no toggle needed — on terminals that report their pixel size (ghostty, Kitty, foot). Terminals without this support fall back to the static max_width and max_height values.

Contributors

aier9500

Changelog

8/10/26, 8:02 PM

View All Changelog

• 0f3b1-Added Kitty guide, mirror of Ghostty Guide, as default modern terminal recommendation.on 8/10/26
• 3c19f-Fedora guide: codecs, RPM Fusion, firmware, hardware decodeon 8/3/26
• c1fd3-Install via terra repo: ghostty and yazion 7/23/26
• eb0c5-docs(guides): serve downloads same-origin as zips, not GitHub linkson 7/13/26
• 9f39d-iteration 1 yazi improvementon 6/22/26
• 87203-Updated configs from canonical setup aierNix.on 6/19/26
• b504d-yazi custom go-to shortcuts and better viisibility and popupson 6/16/26
• 93096-Yazi image preview guideon 6/11/26
• 8f98a-Yazion 6/11/26