Separate Yazi's configuration, then wire up file openers.

Making a file manager comfortable to use usually does not require installing a collection of plugins first. Start by separating “how the list is displayed,” “which program receives a file,” and “which key triggers an action,” and you can check the configuration layer by layer. The examples in this article have been checked against Yazi 26.9.1; confirm the version of an existing configuration before migrating its fields.

Separate configuration responsibilities first#

On Unix systems, user configuration normally lives in ~/.config/yazi/; Windows uses %AppData%\yazi\config\. If a user file does not exist, the release's built-in values apply, so you only need to write the parts you want to change. Copying the complete default files freezes that release's defaults into your own configuration, making it harder after an upgrade to tell which settings you deliberately chose. [1]

To test another configuration, you can launch once with a separate directory. The following changes only this process's configuration source; it does not replace the default directory. Yazi also supports vfs.toml for virtual filesystem configuration. For ordinary local browsing, understanding the first three TOML files is enough to start.

YAZI_CONFIG_HOME="$HOME/.config/yazi-test" yazi

Express browsing preferences with a small configuration#

[mgr] controls the list. The three column ratios represent the parent directory, current directory, and preview, in that order; [1, 4, 3] divides the available width into eight parts. Setting a column to zero hides it, but you cannot set every column to zero. The example below uses natural sorting, which places 2.md before 10.md.

# yazi.toml
[mgr]
ratio = [1, 4, 3]
sort_by = "natural"
sort_dir_first = true
sort_sensitive = false
sort_reverse = false
show_hidden = true
show_symlink = true
linemode = "mtime"
scrolloff = 5

The time-sorting values are mtime and btime; the explanatory words “modified” and “created” are not configuration values. linemode controls what appears on the right side of the list and is separate from sorting: displaying modification times does not mean sorting by them. Fields from older notes, such as [manager] and tab_width, should not be dropped straight into a current configuration either. Using the corresponding release's preset as your baseline is more reliable than applying a configuration patch of unknown age. [2]

Openers define commands and process relationships#

[opener] names groups of commands. The command group itself does not match file types; it specifies how a program starts, which platforms it supports, and whether Yazi yields the terminal. The following example requires Neovim, mpv, and xdg-open to already be installed, handling editing, playback, and the desktop's default applications respectively.

# yazi.toml
[opener]
edit = [
  { run = "nvim %s", block = true, for = "unix", desc = "Edit in Neovim" },
]
play = [
  { run = "mpv %s", orphan = true, for = "unix", desc = "Play in mpv" },
]
desktop = [
  { run = "xdg-open %s1", for = "linux", desc = "Desktop application" },
]

block = true gives an interactive program control of the terminal until it exits, then returns to Yazi; terminal editors should use this mode. orphan = true detaches the process from Yazi's task scheduling, allowing it to continue after Yazi exits. Setting only block = false does not detach it from scheduling and should not be interpreted as fully “launch and forget.” [3]

The current interface uses %s for all selected file paths, %s1 for the first, and %d1 for the first file's parent directory. Yazi escapes substituted paths for the shell context; do not wrap the entire %s in double quotes as a single argument. xdg-open accepts one file at a time, so the example uses %s1. The $@ seen in older tutorials is not one of these format parameters; copying it into the current version changes the command's meaning.

Rules decide which files go to which programs#

Now route files to their handlers. Add the following to the same yazi.toml: code files go to the editor first, HTML offers a desktop application and an editor, and media goes to the player. This uses prepend_rules to place the rules before the defaults while preserving default behavior for archives, empty files, and other cases not covered here.

[open]
prepend_rules = [
  { url = "*.{md,txt,nix,rs,py,js,ts,json,toml,yaml,lua}", use = "edit" },
  { url = "*.html", use = ["desktop", "edit"] },
  { mime = "{audio,video}/*", use = "play" },
  { mime = "image/*", use = "desktop" },
]

url matches a URL using a glob, mime matches the detected MIME type, and use refers to the opener names above. Migrate name in older rules to url. Ordinary opening executes the first available command supplied by the matching rule; interactive opening lists all available commands supplied by that rule. The HTML example therefore defaults to a desktop application while letting you choose an editor for an individual opening. [4]

Do not switch to rules = [...] merely to add one rule: it replaces the entire set of default rules. append_rules adds rules afterward, but its wildcard fallback takes precedence over the default fallback, so “written last” does not necessarily mean “absolute lowest priority.” When troubleshooting, first check whether an earlier specific rule matched, then examine the fallback.

Keybindings invoke actions; they are not opening rules#

By default, l only enters directories; o or Enter opens files, and O opens the “Open with” menu. To add a bookmark or an explicit interactive-open key, put the binding in keymap.toml, not yazi.toml.

# keymap.toml
[mgr]
prepend_keymap = [
  { on = ["g", "p"], run = "cd ~/Projects", desc = "Go to projects" },
  { on = ["g", "<Space>"], run = "cd --interactive", desc = "Enter a directory path" },
  { on = "<C-o>", run = "open --interactive", desc = "Choose an opener" },
]

on = ["g", "p"] means press g and then p, not a key chord; Ctrl combinations use forms such as <C-o>. Yazi finds the first matching binding in the current interface layer. Prepended entries can override defaults, while appended entries cannot take over a key that has already matched. Setting keymap directly replaces that layer's entire default table. The main list belongs to [mgr]; input boxes, confirmation dialogs, and selection menus belong to [input], [confirm], and [pick] respectively. The same j can therefore do different things in different panels. [5]

Previewing and opening are separate paths#

A successful preview does not mean an external program can open the file, and successfully opening it does not guarantee that the terminal can display images. Previewing uses dimensions, wrapping, and other parameters from [preview], with the appropriate previewer and dependencies handling the content. An opener is used only when you explicitly request another program to launch.

# yazi.toml
[preview]
wrap = "yes"
tab_size = 4
max_width = 800
max_height = 1000
image_filter = "triangle"
image_quality = 75

After changing the maximum image dimensions, old cached images may remain; the current cleanup command is ya cache clear. Image quality ranges from 50–90, and filter names include nearest, triangle, catmull-rom, and lanczos3. Do not copy sixel_fraction or catmull-roman from older notes, or use an external program's name as though it were a built-in preloader. For ordinary use, keep the default previewer/preloader tables initially; when adopting a plugin, add only the rules you specifically need.

Troubleshoot by version and execution path#

When something “has no effect,” follow the execution path: version and configuration directory → TOML fields → current key action → matched rule → available opener → external program. Handle incorrect paths, incorrect rules, and missing programs separately; repeatedly clearing the cache will not fix a misspelled field.

yazi --version
ya --version
ya env
command -v nvim
command -v mpv
command -v xdg-open

ya and yazi should use the same version. In 26.9.1, use ya env to view environment and configuration information. This version has no --debug or --clear-cache startup options, nor any general guarantee that ya pub dump retrieves the default configuration. To inspect defaults, consult the preset for the matching version. For file-type questions, press Tab to open details; for keybinding conflicts, use ~ or F1 to view current help. These findings come from checking documentation and source code, not from completed runtime verification on any particular machine. [6]