Plugins (BETA)
You can extend Yazi's functionality through Lua plugins, which need to be placed in the plugins
subdirectory of Yazi's configuration directory, so either:
~/.config/yazi/plugins/
on Unix-like systems.C:\Users\USERNAME\AppData\Roaming\yazi\config\plugins\
on Windows.
~/.config/yazi/
├── init.lua
├── plugins/
│ ├── foo.yazi/
│ └── bar.yazi/
└── yazi.toml
Each plugin is a directory with a kebab-case name, ending in .yazi
, and containing at least the following files:
~/.config/yazi/plugins/bar.yazi/
├── init.lua
├── README.md
└── LICENSE
Where:
init.lua
is the entry point of this plugin.README.md
is the documentation of this plugin.LICENSE
is the license file for this plugin.
Usage
A plugin has two usages:
- Functional plugin: Bind the
plugin
command to a key inkeymap.toml
, and activate it by pressing the key. - Custom previewers, preloaders: Configure them as
previewers
orpreloaders
in your[plugin]
ofyazi.toml
file.
Functional plugin
You can bind a plugin
command to a specific key in your keymap.toml
with:
Argument/Option | Description |
---|---|
[name] | The name of the plugin to run. |
--sync | Run the plugin in a sync context. |
--args=[args] | Shell-style arguments passed to the plugin. |
For example, plugin test --sync --args='hello world'
will run the test
plugin with the arguments hello
and world
in a sync context.
To receive the arguments in the plugin, use args
:
-- ~/.config/yazi/plugins/test.yazi/init.lua
return {
entry = function(self, args)
ya.err(args[1]) -- "hello"
ya.err(args[2]) -- "world"
end,
}
Sync vs Async
The plugin system is designed with an async-first philosophy. Therefore, unless specifically specified, such as the --sync
for the plugin
command, all plugins run in an async context.
There is one exception - all init.lua
are synchronous, which includes:
- The
init.lua
for Yazi itself, i.e.~/.config/yazi/init.lua
. - The
init.lua
for each plugin, e.g.~/.config/yazi/plugins/bar.yazi/init.lua
.
This is because init.lua
is commonly used to initialize plugin configurations, and this process is synchronous:
-- ~/.config/yazi/init.lua
require("bar"):setup {
key1 = "value1",
key2 = "value2",
-- ...
}
-- ~/.config/yazi/plugins/bar.yazi/init.lua
return {
setup = function(state, opts)
-- Save the user configuration to the plugin's state
state.key1 = opts.key1
state.key2 = opts.key2
end,
}