yazi.toml

Configure Yazi’s file manager behavior, preview settings, and task system

The yazi.toml file controls Yazi’s core functionality including the file manager, preview pane, file opening behavior, and background tasks.

File Location

• Unix-like systems: ~/.config/yazi/yazi.toml
• Windows: %AppData%\yazi\config\yazi.toml

Configuration Sections

[mgr] - Manager Settings

Controls the main file manager interface.

ratio · array · default: "[1, 4, 3]"

Column width ratios [parent, current, preview]. The values represent relative proportions.

sort_by · string · default: "alphabetical"

Default sort method. Options: alphabetical, natural, size, mtime, btime, extension, random

sort_sensitive · boolean · default: "false"

Case-sensitive sorting when true

sort_reverse · boolean · default: "false"

Reverse sort order when true

sort_dir_first · boolean · default: "true"

Show directories before files when true

sort_translit · boolean · default: "false"

Transliterate special characters for sorting when true

sort_fallback · string · default: "alphabetical"

Fallback sort method when the primary sort produces equal values. Same options as sort_by.

linemode · string · default: "none"

Information to show in file list. Options: none, size, permissions, mtime, btime, owner

show_hidden · boolean · default: "false"

Show hidden files by default when true

show_symlink · boolean · default: "true"

Show symlink targets when true

scrolloff · integer · default: "5"

Number of lines to keep above/below cursor when scrolling

mouse_events · array · default: "[\"click\", \"scroll\"]"

Enabled mouse events. Options: click, scroll, drag, drop

Example

[mgr]
ratio = [1, 3, 4]  # Larger preview pane
sort_by = "mtime"  # Sort by modification time
sort_reverse = true  # Newest first
linemode = "size"  # Show file sizes
scrolloff = 10  # More padding

[preview] - Preview Settings

Controls the preview pane behavior.

wrap · string · default: "no"

Line wrapping behavior. Options: no, wrap

tab_size · integer · default: "2"

Number of spaces for tab characters in text preview

max_width · integer · default: "600"

Maximum preview width in pixels for image scaling

max_height · integer · default: "900"

Maximum preview height in pixels for image scaling

cache_dir · string · default: ""

Directory for preview cache. Empty string uses system cache directory.

image_delay · integer · default: "30"

Delay in milliseconds before loading image preview (0-100)

image_filter · string · default: "triangle"

Image scaling filter. Options: nearest, triangle, catmull-rom, gaussian, lanczos3

image_quality · integer · default: "75"

JPEG quality for cached images (50-90)

ueberzug_scale · float · default: "1"

Scale factor for Ueberzug image protocol

ueberzug_offset · array · default: "[0, 0, 0, 0]"

Offset [x, y, width, height] for Ueberzug images

Example

[preview]
wrap = "wrap"
tab_size = 4
max_width = 1920
max_height = 1080
image_delay = 50
image_filter = "lanczos3"
image_quality = 85

[opener] - External Programs

Defines external programs for opening files.

opener.<name> · array

Array of opener definitions. Each opener has:

• run - Command to execute (use %s for selected files)
• desc - Description shown in picker
• for - Platform filter: unix, linux, macos, windows, android
• block - Block terminal until command finishes (optional)
• orphan - Detach from terminal (optional)

Example

[opener]
edit = [
  { run = "${EDITOR:-vi} %s", desc = "$EDITOR", for = "unix", block = true },
  { run = "code %s", desc = "VS Code", for = "windows", orphan = true },
]
open = [
  { run = "xdg-open %s", desc = "Open", for = "linux" },
  { run = "open %s", desc = "Open", for = "macos" },
  { run = 'start "" %s', desc = "Open", for = "windows", orphan = true },
]

[open] - File Opening Rules

Defines which openers to use for different file types.

rules · array

Array of rules matching files to openers. Each rule has:

• url - URL pattern (e.g., */, *.txt)
• mime - MIME type pattern (e.g., image/*, text/plain)
• use - Array of opener names or single opener name

Example

[open]
rules = [
  { url = "*/", use = ["edit", "open", "reveal"] },
  { mime = "text/*", use = ["edit", "reveal"] },
  { mime = "image/*", use = ["open", "reveal"] },
  { mime = "{audio,video}/*", use = ["play", "reveal"] },
  { url = "*", use = ["open", "reveal"] },
]

[tasks] - Task System

Controls background task processing.

file_workers · integer · default: "3"

Number of worker threads for file operations (min: 1)

plugin_workers · integer · default: "5"

Number of worker threads for plugin operations (min: 1)

fetch_workers · integer · default: "5"

Number of worker threads for fetching operations (min: 1)

preload_workers · integer · default: "2"

Number of worker threads for preloading (min: 1)

process_workers · integer · default: "5"

Number of worker threads for process operations (min: 1)

bizarre_retry · integer · default: "3"

Number of retries for failed bizarre tasks (min: 1)

image_alloc · integer · default: "536870912"

Memory allocation limit for images in bytes (default: 512MB)

image_bound · array · default: "[10000, 10000]"

Maximum image dimensions [width, height] in pixels

suppress_preload · boolean · default: "false"

Suppress preload operations when true

Example

[tasks]
file_workers = 5
plugin_workers = 10
image_alloc = 1073741824  # 1GB
image_bound = [15000, 15000]

[plugin] - Plugin Configuration

Configures plugin behavior for file type detection, preview, and more.

Fetchers

Plugins that fetch file metadata:

[[plugin.fetchers]]
id = "mime"
url = "*/"
run = "mime.dir"
prio = "high"

• id - Plugin identifier
• url - URL pattern to match
• run - Plugin function to execute
• prio - Priority: high, normal, low

Spotters

Plugins that generate file details:

[[plugin.spotters]]
url = "*/"
run = "folder"

Can also match by MIME type:

[[plugin.spotters]]
mime = "image/*"
run = "image"

Preloaders

Plugins that preload file data:

[[plugin.preloaders]]
mime = "image/*"
run = "image"

Previewers

Plugins that generate file previews:

[[plugin.previewers]]
url = "*/"
run = "folder"

[[plugin.previewers]]
mime = "text/*"
run = "code"

[input] - Input Dialog

Controls input dialog appearance and position.

cursor_blink · boolean · default: "false"

Enable cursor blinking when true

cd_title · string · default: "Change directory:"

Title for the change directory dialog

cd_origin · string · default: "top-center"

Dialog origin position. Options: center, top-left, top-center, top-right, bottom-left, bottom-center, bottom-right, hovered

cd_offset · array · default: "[0, 2, 50, 3]"

Dialog offset [x, y, width, height]

Similar settings exist for: create_*, rename_*, filter_*, find_*, search_*, shell_*

[confirm] - Confirmation Dialog

Controls confirmation dialog appearance.

trash_title · string · default: "Trash {n} selected file{s}?"

Title for trash confirmation. Use {n} for count, {s} for plural.

trash_origin · string · default: "center"

Dialog origin position

trash_offset · array · default: "[0, 0, 70, 20]"

Dialog offset [x, y, width, height]

Similar settings exist for: delete_*, overwrite_*, quit_*

[pick] - Picker Dialog

Controls the file opener picker.

open_title · string · default: "Open with:"

Title for the opener picker

open_origin · string · default: "hovered"

Dialog origin position

open_offset · array · default: "[0, 1, 50, 7]"

Dialog offset [x, y, width, height]

[which] - Which-Key Popup

Controls the which-key popup that shows available keybindings.

sort_by · string · default: "none"

Sort method for keybindings. Options: none, alphabetical

sort_sensitive · boolean · default: "false"

Case-sensitive sorting when true

sort_reverse · boolean · default: "false"

Reverse sort order when true

sort_translit · boolean · default: "false"

Transliterate special characters for sorting when true

Complete Example

"$schema" = "https://yazi-rs.github.io/schemas/yazi.json"

[mgr]
ratio = [1, 4, 3]
sort_by = "natural"
sort_sensitive = false
sort_reverse = false
sort_dir_first = true
linemode = "size"
show_hidden = false
show_symlink = true
scrolloff = 5

[preview]
wrap = "no"
tab_size = 2
max_width = 600
max_height = 900
image_delay = 30
image_filter = "triangle"
image_quality = 75

[opener]
edit = [
  { run = "${EDITOR:-vi} %s", desc = "$EDITOR", for = "unix", block = true },
]
open = [
  { run = "xdg-open %s", desc = "Open", for = "linux" },
]

[open]
rules = [
  { url = "*/", use = ["edit", "open"] },
  { mime = "text/*", use = ["edit"] },
  { mime = "image/*", use = ["open"] },
  { url = "*", use = ["open"] },
]

[tasks]
file_workers = 3
plugin_workers = 5
fetch_workers = 5
preload_workers = 2
process_workers = 5

See Also

• Keymap Configuration
• Theme Configuration
• Openers Configuration