Skip to main content

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 features a powerful plugin system built on Lua, allowing you to extend and customize every aspect of the file manager. Plugins can add new functionality, customize the UI, preview files, and fetch metadata.

​
Plugin Types

Yazi supports four main types of plugins:

​
1. UI Plugins (Components)

UI plugins customize the visual interface by overriding built-in components:
  • Header - Top bar showing current directory and status
  • Status - Bottom bar with file info and position
  • Entity - Individual file/folder rendering
  • Tab - Tab content area
  • Tabs - Tab bar
  • And more…
UI plugins allow you to completely redesign Yazi’s appearance and layout.

​
2. Functional Plugins

Functional plugins add new commands and behaviors:
  • Interactive commands (e.g., zoxide for directory jumping)
  • Batch operations (e.g., extract for archive extraction)
  • Integration with external tools (e.g., fzf for fuzzy finding)
  • Custom file operations
These plugins typically have an entry() function that executes when called.

​
3. Previewers

Previewer plugins generate file previews in the preview pane:
  • Text/Code - Syntax highlighting for code files
  • Images - Display images inline
  • Videos - Extract and show video thumbnails
  • Archives - List archive contents
  • PDFs - Convert PDF pages to images
  • Folders - Show folder contents
Previewers implement peek(), seek(), and optionally preload() methods.

​
4. Fetchers

Fetcher plugins retrieve file metadata asynchronously:
  • MIME types - Detect file types
  • Git status - Show version control info
  • File metadata - Extract custom properties
Fetchers implement a fetch() method that processes files in batches.

​
5. Spotters

Spotter plugins provide detailed file information in the info panel:
  • Show file properties and metadata
  • Display image dimensions and format
  • Video codec and duration info
  • Custom file analysis
Spotters implement a spot() method that returns formatted data.

​
Plugin Configuration

Plugins are configured in yazi.toml under the [plugin] section: 
[plugin]
fetchers = [
  { id = "mime", url = "*/", run = "mime.dir", prio = "high" },
  { id = "mime", url = "local://*", run = "mime.local", prio = "high" },
]

spotters = [
  { url = "*/", run = "folder" },
  { mime = "text/*", run = "code" },
  { mime = "image/*", run = "image" },
  { mime = "video/*", run = "video" },
]

preloaders = [
  { mime = "image/*", run = "image" },
  { mime = "video/*", run = "video" },
  { mime = "application/pdf", run = "pdf" },
]

previewers = [
  { url = "*/", run = "folder" },
  { mime = "text/*", run = "code" },
  { mime = "image/*", run = "image" },
  { mime = "video/*", run = "video" },
  { mime = "application/pdf", run = "pdf" },
  { mime = "application/{zip,rar,7z*,tar,gzip}", run = "archive" },
]

​
Plugin Matching

Plugins can be matched by:
  • URL patterns - url = "*/*.jpg", url = "*/"
  • MIME types - mime = "image/*", mime = "text/*"
  • Priority - prio = "high" (for fetchers)

​
Plugin Location

Plugins are stored in:
  • Linux/macOS: ~/.config/yazi/plugins/
  • Windows: %APPDATA%\yazi\config\plugins\
Yazi also includes preset plugins in its installation directory.

​
Plugin Structure

Each plugin is a directory or single .lua file: 
plugins/
├── my-plugin/
│   ├── init.lua          # Main plugin file
│   └── utils.lua         # Helper modules
└── simple-plugin.lua     # Single-file plugin
For directory-based plugins, Yazi loads init.lua by default.

​
Calling Plugins

​
From keymap.toml

Bind plugins to keys: 
[[manager.prepend_keymap]]
on = [ "z" ]
run = "plugin zoxide"
desc = "Jump to directory with zoxide"

[[manager.prepend_keymap]]
on = [ "f" ]
run = "plugin fzf"
desc = "Fuzzy find files"

​
From Command Line

Call plugins with arguments: 
ya pub extract /path/to/archive.zip

​
From Other Plugins

Plugins can call each other: 
-- Call another plugin
ya.emit("plugin", { "plugin-name", arg1, arg2 })

-- Require shared code
local utils = require("my-utils")

​
Next Steps

Creating Plugins

Learn how to create your own plugins

UI Plugins

Customize Yazi’s appearance

Functional Plugins

Add new commands and behaviors

Previewers

Create custom file previewers

Fetchers

Build metadata fetchers

Build docs developers (and LLMs) love

Get started for freeTalk to us