> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField path="ratio" type="array" default="[1, 4, 3]">
  Column width ratios `[parent, current, preview]`. The values represent relative proportions.
</ParamField>

<ParamField path="sort_by" type="string" default="alphabetical">
  Default sort method. Options: `alphabetical`, `natural`, `size`, `mtime`, `btime`, `extension`, `random`
</ParamField>

<ParamField path="sort_sensitive" type="boolean" default="false">
  Case-sensitive sorting when `true`
</ParamField>

<ParamField path="sort_reverse" type="boolean" default="false">
  Reverse sort order when `true`
</ParamField>

<ParamField path="sort_dir_first" type="boolean" default="true">
  Show directories before files when `true`
</ParamField>

<ParamField path="sort_translit" type="boolean" default="false">
  Transliterate special characters for sorting when `true`
</ParamField>

<ParamField path="sort_fallback" type="string" default="alphabetical">
  Fallback sort method when the primary sort produces equal values. Same options as `sort_by`.
</ParamField>

<ParamField path="linemode" type="string" default="none">
  Information to show in file list. Options: `none`, `size`, `permissions`, `mtime`, `btime`, `owner`
</ParamField>

<ParamField path="show_hidden" type="boolean" default="false">
  Show hidden files by default when `true`
</ParamField>

<ParamField path="show_symlink" type="boolean" default="true">
  Show symlink targets when `true`
</ParamField>

<ParamField path="scrolloff" type="integer" default="5">
  Number of lines to keep above/below cursor when scrolling
</ParamField>

<ParamField path="mouse_events" type="array" default="[&#x22;click&#x22;, &#x22;scroll&#x22;]">
  Enabled mouse events. Options: `click`, `scroll`, `drag`, `drop`
</ParamField>

#### Example

```toml theme={null}
[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.

<ParamField path="wrap" type="string" default="no">
  Line wrapping behavior. Options: `no`, `wrap`
</ParamField>

<ParamField path="tab_size" type="integer" default="2">
  Number of spaces for tab characters in text preview
</ParamField>

<ParamField path="max_width" type="integer" default="600">
  Maximum preview width in pixels for image scaling
</ParamField>

<ParamField path="max_height" type="integer" default="900">
  Maximum preview height in pixels for image scaling
</ParamField>

<ParamField path="cache_dir" type="string" default="">
  Directory for preview cache. Empty string uses system cache directory.
</ParamField>

<ParamField path="image_delay" type="integer" default="30">
  Delay in milliseconds before loading image preview (0-100)
</ParamField>

<ParamField path="image_filter" type="string" default="triangle">
  Image scaling filter. Options: `nearest`, `triangle`, `catmull-rom`, `gaussian`, `lanczos3`
</ParamField>

<ParamField path="image_quality" type="integer" default="75">
  JPEG quality for cached images (50-90)
</ParamField>

<ParamField path="ueberzug_scale" type="float" default="1">
  Scale factor for Ueberzug image protocol
</ParamField>

<ParamField path="ueberzug_offset" type="array" default="[0, 0, 0, 0]">
  Offset `[x, y, width, height]` for Ueberzug images
</ParamField>

#### Example

```toml theme={null}
[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.

<ParamField path="opener.<name>" type="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)
</ParamField>

#### Example

```toml theme={null}
[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.

<ParamField path="rules" type="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
</ParamField>

#### Example

```toml theme={null}
[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.

<ParamField path="file_workers" type="integer" default="3">
  Number of worker threads for file operations (min: 1)
</ParamField>

<ParamField path="plugin_workers" type="integer" default="5">
  Number of worker threads for plugin operations (min: 1)
</ParamField>

<ParamField path="fetch_workers" type="integer" default="5">
  Number of worker threads for fetching operations (min: 1)
</ParamField>

<ParamField path="preload_workers" type="integer" default="2">
  Number of worker threads for preloading (min: 1)
</ParamField>

<ParamField path="process_workers" type="integer" default="5">
  Number of worker threads for process operations (min: 1)
</ParamField>

<ParamField path="bizarre_retry" type="integer" default="3">
  Number of retries for failed bizarre tasks (min: 1)
</ParamField>

<ParamField path="image_alloc" type="integer" default="536870912">
  Memory allocation limit for images in bytes (default: 512MB)
</ParamField>

<ParamField path="image_bound" type="array" default="[10000, 10000]">
  Maximum image dimensions `[width, height]` in pixels
</ParamField>

<ParamField path="suppress_preload" type="boolean" default="false">
  Suppress preload operations when `true`
</ParamField>

#### Example

```toml theme={null}
[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.

<Accordion title="Fetchers">
  Plugins that fetch file metadata:

  ```toml theme={null}
  [[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`
</Accordion>

<Accordion title="Spotters">
  Plugins that generate file details:

  ```toml theme={null}
  [[plugin.spotters]]
  url = "*/"
  run = "folder"
  ```

  Can also match by MIME type:

  ```toml theme={null}
  [[plugin.spotters]]
  mime = "image/*"
  run = "image"
  ```
</Accordion>

<Accordion title="Preloaders">
  Plugins that preload file data:

  ```toml theme={null}
  [[plugin.preloaders]]
  mime = "image/*"
  run = "image"
  ```
</Accordion>

<Accordion title="Previewers">
  Plugins that generate file previews:

  ```toml theme={null}
  [[plugin.previewers]]
  url = "*/"
  run = "folder"

  [[plugin.previewers]]
  mime = "text/*"
  run = "code"
  ```
</Accordion>

### \[input] - Input Dialog

Controls input dialog appearance and position.

<ParamField path="cursor_blink" type="boolean" default="false">
  Enable cursor blinking when `true`
</ParamField>

<ParamField path="cd_title" type="string" default="Change directory:">
  Title for the change directory dialog
</ParamField>

<ParamField path="cd_origin" type="string" default="top-center">
  Dialog origin position. Options: `center`, `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`, `hovered`
</ParamField>

<ParamField path="cd_offset" type="array" default="[0, 2, 50, 3]">
  Dialog offset `[x, y, width, height]`
</ParamField>

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

### \[confirm] - Confirmation Dialog

Controls confirmation dialog appearance.

<ParamField path="trash_title" type="string" default="Trash {n} selected file{s}?">
  Title for trash confirmation. Use `{n}` for count, `{s}` for plural.
</ParamField>

<ParamField path="trash_origin" type="string" default="center">
  Dialog origin position
</ParamField>

<ParamField path="trash_offset" type="array" default="[0, 0, 70, 20]">
  Dialog offset `[x, y, width, height]`
</ParamField>

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

### \[pick] - Picker Dialog

Controls the file opener picker.

<ParamField path="open_title" type="string" default="Open with:">
  Title for the opener picker
</ParamField>

<ParamField path="open_origin" type="string" default="hovered">
  Dialog origin position
</ParamField>

<ParamField path="open_offset" type="array" default="[0, 1, 50, 7]">
  Dialog offset `[x, y, width, height]`
</ParamField>

### \[which] - Which-Key Popup

Controls the which-key popup that shows available keybindings.

<ParamField path="sort_by" type="string" default="none">
  Sort method for keybindings. Options: `none`, `alphabetical`
</ParamField>

<ParamField path="sort_sensitive" type="boolean" default="false">
  Case-sensitive sorting when `true`
</ParamField>

<ParamField path="sort_reverse" type="boolean" default="false">
  Reverse sort order when `true`
</ParamField>

<ParamField path="sort_translit" type="boolean" default="false">
  Transliterate special characters for sorting when `true`
</ParamField>

## Complete Example

```toml theme={null}
"$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](configuration/keymap)
* [Theme Configuration](configuration/theme)
* [Openers Configuration](configuration/openers)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.