Yazi

https://yazi-rs.github.io/docs/
Admin
Yazi is a fast, asynchronous terminal file manager written in Rust, featuring async I/O, task...
Tokens:96,859
Snippets:1,096
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install and start SSH server in WSL

Source: https://yazi-rs.github.io/docs/image-preview

Install openssh-server and start the SSH service in WSL to enable WezTerm's SSH connection for image preview.

```bash
sudo apt install openssh-server  

sudo service ssh restart  

```

--------------------------------

### Plugin setup: init.lua and my-plugin.yazi/main.lua

Source: https://yazi-rs.github.io/docs/plugins/overview

Shows how to reference a plugin's setup function from the synchronous init.lua and how the plugin's setup method saves user options into its state. The init.lua passes a table of key-value pairs that the plugin's setup function maps onto the plugin state.

```lua
-- ~/.config/yazi/init.lua  

require("my-plugin"):setup {  
	key1 = "value1",  
	key2 = "value2",  
	-- ...  
}  


```

```lua
-- ~/.config/yazi/plugins/my-plugin.yazi/main.lua  

return {  
	setup = function(state, opts)  
		-- Save the user configuration to the plugin's state  
		state.key1 = opts.key1  
		state.key2 = opts.key2  
	end,  
}  


```

--------------------------------

### Install Yazi via Snap

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi from the Snap Store with classic confinement.

```bash
sudo snap install yazi --classic  

```

--------------------------------

### Layout Creation Example

Source: https://yazi-rs.github.io/docs/plugins/layout

Example showing how to create a layout with two equal horizontal areas.

```APIDOC
## Layout Creation Example

### Description
Creates a layout with two equal horizontal areas.

### Code
```lua
local areas = ui.Layout()  

    :direction(ui.Layout.HORIZONTAL)  

    :constraints({ ui.Constraint.Percentage(50), ui.Constraint.Percentage(50) })  

    :split(area)  

  

local left = areas[1] -- The first rect  

local right = areas[2] -- The second rect  
```
```

--------------------------------

### Nix flake.nix setup for Yazi

Source: https://yazi-rs.github.io/docs/installation

Basic flake.nix configuration to install Yazi system-wide or for a specific user with Nix. Includes an optional override to add RAR extraction support via _7zz-rar.

```nix
{

	inputs = {  

		nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";  

		home-manager = {  

			url = "github:nix-community/home-manager/release-23.11";  
			inputs.nixpkgs.follows = "nixpkgs";  

		};  

		yazi.url = "github:sxyazi/yazi";  
	};  

	outputs = { nixpkgs, home-manager, yazi, ... }: {  
		# To install Yazi system-wide:  
		nixosConfigurations = {  
			nixos = nixpkgs.lib.nixosSystem {  
				modules = [  
					({ pkgs, ... }: {  
						environment.systemPackages = [  
							(yazi.packages.${pkgs.stdenv.hostPlatform.system}.default.override {  
								_7zz = pkgs._7zz-rar;  # Support for RAR extraction  
							})  
						];  
					})  
				];  
			};  
   };  # <-- missing closing brace for nixosConfigurations? Actually the original has it. Let me check the original source. The original source is: https://yazi-rs.github.io/docs/installation#nix-flakes. I'll use the exact code{}```json  // Ensure valid JSON with no trailing commas. Escaping: 
 for newlines, 	 for tabs, " for quotes, \ for backsl```json
{
  
```

--------------------------------

### Install Yazi via PyPI

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi from PyPI using pipx or uv.

```bash
pipx install yazi-bin  

# Or  

uv tool install yazi-bin  

```

--------------------------------

### Install Yazi via Mise

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi globally using Mise.

```bash
mise use -g yazi  

```

--------------------------------

### Install Yazi with x-cmd

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi and its dependencies using the x-cmd environment manager.

```bash
x env use yazi ffmpeg 7zz jq fd rg fzf zoxide magick  
```

--------------------------------

### Install Yazi nightly via Snap

Source: https://yazi-rs.github.io/docs/installation

Installs the nightly version of Yazi from the Snap Store.

```bash
sudo snap install yazi --classic --edge  

```

--------------------------------

### Start Yazi with a VFS working directory

Source: https://yazi-rs.github.io/docs/configuration/vfs

Command to start Yazi with the SFTP service 'my-server' as the working directory, using the scheme://domain combination.

```bash
yazi sftp://my-server  



```

--------------------------------

### Install locked plugins with ya pkg install

Source: https://yazi-rs.github.io/docs/cli

Installs all plugins with locked versions from package.toml on a new system.

```bash
ya pkg install  
```

--------------------------------

### Install Rust toolchain via rustup

Source: https://yazi-rs.github.io/docs/installation

Downloads and installs the latest stable Rust toolchain using rustup, then updates it.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh  

rustup update  
```

--------------------------------

### Install yazi-build via cargo

Source: https://yazi-rs.github.io/docs/installation

Installs the yazi-build package via cargo, which installs yazi-fm and yazi-cli.

```bash
cargo install --force yazi-build  
```

--------------------------------

### Yazi [opener] configuration example

Source: https://yazi-rs.github.io/docs/configuration/yazi

Example configuration defining openers for play, edit, and open actions, with platform-specific commands for Unix and Windows. The 'play' opener uses 'orphan = true' to keep the process running, 'edit' uses 'block = true' for interactive programs, and 'open' uses 'xdg-open' with a description.

```toml
[opener]  

play = [  

	{ run = "mpv %s", orphan = true, for = "unix" },  

	{ run = '"C:\Program Files\mpv.exe" %s', orphan = true, for = "windows" }  

]  

edit = [  

	{ run = "$EDITOR %s", block = true, for = "unix" },  

	{ run = "%EDITOR% %s", block = true, for = "windows" },  

]  

open = [  

	{ run = "xdg-open %s1", desc = "Open" },  

]  

# ...  
```

--------------------------------

### Launch Yazi

Source: https://yazi-rs.github.io/docs/quick-start

Starts the Yazi file manager from the command line. Press q to quit, or F1 or ~ to open the help menu.

```text
yazi  
```

--------------------------------

### Install Yazi nightly binary from AUR

Source: https://yazi-rs.github.io/docs/installation

Install the official nightly release binary of Yazi from AUR, built from the latest code within the past 6 hours.

```bash
paru -S yazi-nightly-bin ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick
```

--------------------------------

### Install Yazi binary release with cargo-binstall

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi's binary release using cargo-binstall.

```bash
cargo binstall yazi-fm yazi-cli  
```

--------------------------------

### Install Yazi and dependencies on Void Linux

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi and its recommended dependencies (ffmpeg, 7zip, jq, poppler, fd, ripgrep, fzf, zoxide, resvg, ImageMagick) using the xbps-install package manager.

```bash
sudo xbps-install -S yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg ImageMagick  
```

--------------------------------

### Install Yazi and optional dependencies via Homebrew

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi and optional dependencies using Homebrew. Run `brew update` first to ensure Homebrew is up-to-date.

```bash
brew install yazi ffmpeg-full sevenzip jq poppler fd ripgrep fzf zoxide resvg imagemagick-full font-symbols-only-nerd-font  

brew link ffmpeg-full imagemagick-full -f --overwrite  
```

--------------------------------

### Install Yazi via MSYS2 pacman

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi and its recommended dependencies via pacman on MSYS2.

```bash
pacman -S mingw-w64-ucrt-x86_64-{yazi,ffmpeg,7zip,jq,poppler,fd,ripgrep,fzf,zoxide,imagemagick}  

```

--------------------------------

### Install Yazi via APT repository (Stable)

Source: https://yazi-rs.github.io/docs/installation

Adds the official Yazi APT repository and installs the stable build on Debian/Ubuntu.

```bash
curl -fsSL https://yazi-rs.github.io/builds/yazi-keyring.gpg | sudo tee /usr/share/keyrings/yazi-keyring.gpg >/dev/null  
echo 'deb [signed-by=/usr/share/keyrings/yazi-keyring.gpg] https://yazi-rs.github.io/builds/ stable main' | sudo tee /etc/apt/sources.list.d/yazi.list >/dev/null  
sudo apt update && sudo apt install yazi  
```

--------------------------------

### Add a plugin with ya pkg add

Source: https://yazi-rs.github.io/docs/cli

Installs a plugin from a GitHub repository. The argument is in the format owner/repo.

```bash
ya pkg add owner/my-plugin  
```

--------------------------------

### Install Yazi on NetBSD with pkgin

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi and its dependencies (ffmpeg7, p7zip, jq, poppler, fd, ripgrep, fzf, zoxide, ImageMagick) on NetBSD using the pkgin package manager.

```bash
pkgin install yazi ffmpeg7 p7zip jq poppler fd ripgrep fzf zoxide ImageMagick  
```

--------------------------------

### Install Yazi via dnf with recommended dependencies

Source: https://yazi-rs.github.io/docs/installation

Enables the unofficial COPR repository and installs Yazi with recommended dependencies.

```bash
dnf copr enable lihaohong/yazi  

dnf install yazi  

```

--------------------------------

### Install Yazi with --HEAD flag via Homebrew

Source: https://yazi-rs.github.io/docs/installation

Installs the most recent development code of Yazi using Homebrew's --HEAD flag.

```bash
brew install yazi --HEAD  
```

--------------------------------

### Install Yazi via dnf without weak dependencies

Source: https://yazi-rs.github.io/docs/installation

Installs only Yazi without weak dependencies using dnf.

```bash
dnf copr enable lihaohong/yazi  

dnf install yazi --setopt=install_weak_deps=False  

```

--------------------------------

### package.toml after adding plugins

Source: https://yazi-rs.github.io/docs/cli

Example of the package.toml file after adding plugins. It locks the plugin versions with rev and hash.

```toml
# ~/.config/yazi/package.toml  

[[plugin.deps]]  

use  = "owner/my-plugin"  

rev  = "0573024"  

hash = "d81b64a39432fcd6224cd75d296e7510"  

  

[[plugin.deps]]  

use  = "yazi-rs/plugins:git"  

rev  = "9a1129c"  

hash = "a8e15d3c21c02a5af41d46ed04778a02"  


```

--------------------------------

### Add a package from a monorepo subdirectory

Source: https://yazi-rs.github.io/docs/cli

Installs a package from a subdirectory of a monorepo. The format is owner/repo:subdir.

```bash
ya pkg add yazi-rs/plugins:git  
```

--------------------------------

### Install Yazi with nix-env on NixOS and non-NixOS

Source: https://yazi-rs.github.io/docs/installation

Use nix-env to install Yazi on NixOS or non-NixOS systems. The NixOS command uses the nixos channel, while the non-NixOS command uses nixpkgs.

```bash
# NixOS:  

nix-env -iA nixos.yazi  

# Not NixOS:  

nix-env -iA nixpkgs.yazi  
```

--------------------------------

### Configure prepend_preloaders for [plugin]

Source: https://yazi-rs.github.io/docs/configuration/yazi

Shows how to add a custom preloader rule by prepending to the default preloaders. The example adds a HEIC preloader by MIME type.

```toml
[plugin]  

prepend_preloaders = [  

	# HEIC preloader  

	{ mime = "image/heic", run = "heic" },  

]  

```

--------------------------------

### macOS: Preview files with the system Quick Look

Source: https://yazi-rs.github.io/docs/tips

Binds Ctrl+P to run `qlmanage -p %s` via the shell, opening the system Quick Look preview for the selected file on macOS. Shared by @UncleGravity.

```toml
[[mgr.prepend_keymap]]

on = "<C-p>"

run = "shell -- qlmanage -p %s"

```

--------------------------------

### Register a custom VFS provider in vfs.toml

Source: https://yazi-rs.github.io/docs/configuration/vfs

Example of registering a custom scheme and domain in vfs.toml. The scheme and domain are 'sftp' and 'my-server' respectively, but any kebab-case names up to 20 characters are allowed. Different scheme-and-domain combos are treated as separate virtual filesystems.

```toml
[sftp.my-server]  

host = "1.2.3.4"  

user = "root"  

port = 22  



```

--------------------------------

### Install Yazi via MacPorts

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi and its dependencies using MacPorts on macOS.

```bash
sudo port install yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide ImageMagick  
```

--------------------------------

### Bookmark keybindings with `cd` in `[[mgr.prepend_keymap]]`

Source: https://yazi-rs.github.io/docs/configuration/keymap

Adds two `g` series keybindings to change to the Downloads and Pictures directories. Each entry uses `[[mgr.prepend_keymap]]` to prepend the keymap, with `on`, `run`, and `desc` fields. This is a simple bookmark feature for the `cd` action.

```toml
[[mgr.prepend_keymap]]  

on   = [ "g", "d" ]  

run  = "cd ~/Downloads"  

desc = "Cd to ~/Downloads"  

  

[[mgr.prepend_keymap]]  

on   = [ "g", "p" ]  

run  = "cd ~/Pictures"  

desc = "Cd to ~/Pictures"  


```

--------------------------------

### Apply set-wallpaper opener to image files

Source: https://yazi-rs.github.io/docs/tips

Adds a prepend_rules entry that matches image MIME types and uses the set-wallpaper opener along with the default open action.

```toml
# yazi.toml  

[[open.prepend_rules]]  

mime = "image/*"  

use  = [ "set-wallpaper", "open" ]  

```

--------------------------------

### Install Yazi on AOSC OS

Source: https://yazi-rs.github.io/docs/installation

Installs Yazi and its dependencies using the AOSC OS package manager (oma).

```bash
sudo oma install yazi ffmpeg p7zip jq poppler fd ripgrep fzf zoxide imagemagick  
```

--------------------------------

### Install Yazi on Arch Linux

Source: https://yazi-rs.github.io/docs/installation

Install Yazi and its optional dependencies on Arch Linux using the official repository.

```bash
sudo pacman -S yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick
```

--------------------------------

### Install latest Git version of Yazi

Source: https://yazi-rs.github.io/docs/installation

Installs the latest Git version of Yazi using cargo from the GitHub repository.

```bash
cargo install --force --git https://github.com/sxyazi/yazi.git yazi-build  
```

--------------------------------

### Show username and hostname in header (init.lua)

Source: https://yazi-rs.github.io/docs/tips

Adds a header component that displays the current username and hostname in blue, but only on Unix-like systems. Returns an empty string for non-Unix targets.

```lua
Header:children_add(function()  

	if ya.target_family() ~= "unix" then  

		return ""  

	end  

	return ui.Span(ya.user_name() .. "@" .. ya.host_name() .. ":"):fg("blue")  

end, 500, Header.LEFT)  
```

--------------------------------

### Bind reveal action to VFS file in keymap.toml

Source: https://yazi-rs.github.io/docs/configuration/vfs

Keymap configuration to bind the 'reveal' action to a file on a VFS. This example maps 'g' then 's' to run 'reveal sftp://my-server//root/dog.jpg'.

```toml
[[mgr.prepend_keymap]]  

on   = [ "g", "s" ]  

run  = "reveal sftp://my-server//root/dog.jpg"  

desc = "Reveal dog.jpg on my-server"  



```

--------------------------------

### Create a List with convenience types

Source: https://yazi-rs.github.io/docs/plugins/layout

Shows the convenience types accepted by ui.List: tables of strings, ui.Line, ui.Span, or a mixed table of all three. Each example is a valid alternative for constructing a list.

```lua
-- Table of string

ui.List { "foo", "bar" }
```

```lua
-- Table of ui.Line

ui.List { ui.Line("foo"), ui.Line("bar") }
```

```lua
-- Table of ui.Span

ui.List { ui.Span("foo"), ui.Span("bar") }
```

```lua
-- Mixed table of string, ui.Line, ui.Span

ui.List { "foo", ui.Line("bar"), ui.Span("baz") }
```

--------------------------------

### Install Yazi Git version from AUR

Source: https://yazi-rs.github.io/docs/installation

Install the latest Git version of Yazi from AUR or Arch Linux CN using paru.

```bash
paru -S yazi-git ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick
```

--------------------------------

### Get username with ya.user_name

Source: https://yazi-rs.github.io/docs/plugins/utils

Gets the username for the given uid, or the current user's name when called with no argument. Available on Unix-like systems only.

```lua
-- Get the current user's name if no argument is provided  

ya.user_name()  

  

-- Get the name of user with id 1000  

ya.user_name(1000)  


```

--------------------------------

### Bind cd action to VFS in keymap.toml

Source: https://yazi-rs.github.io/docs/configuration/vfs

Keymap configuration to bind the 'cd' action to a VFS path. This example maps the 'g' then 's' keys to run 'cd sftp://my-server'.

```toml
[[mgr.prepend_keymap]]  

on   = [ "g", "s" ]  

run  = "cd sftp://my-server"  

desc = "Go to my-server"  



```

--------------------------------

### Get group name with ya.group_name

Source: https://yazi-rs.github.io/docs/plugins/utils

Gets the group name for the given gid, or the current user's group name when called with no argument. Available on Unix-like systems only.

```lua
-- Get the current user's group name if no argument is provided  

ya.group_name()  

  

-- Get the name of group with id 1000  

ya.group_name(1000)  


```

--------------------------------

### Set wallpaper with openers for Hyprland, Swaybg, and macOS

Source: https://yazi-rs.github.io/docs/tips

Defines three set-wallpaper openers in yazi.toml: one for Hyprland using hyprctl hyprpaper, one for Swaybg using killall and swaybg, and one for macOS using osascript. Each is conditioned on the platform (linux or macos) and the Swaybg one sets orphan = true.

```toml
# Linux: Hyprland + Hyprpaper  

[[opener.set-wallpaper]]  

run  = "hyprctl hyprpaper wallpaper ,%s1"  

for  = "linux"  

desc = "Set as wallpaper"  

  

# Linux: Swaybg  

[[opener.set-wallpaper]]  

run  = "killall swaybg; swaybg -m fill -i %s1"  

for  = "linux"  

desc = "Set as wallpaper"  

orphan = true  

  

# macOS  

[[opener.set-wallpaper]]  

run = '''  

	osascript -e 'on run {img}' -e 'tell application "System Events" to set picture of every desktop to img' -e 'end run' %s1  

'''  

for  = "macos"  

desc = "Set as wallpaper"  

```

--------------------------------

### Get or set clipboard content with ya.clipboard

Source: https://yazi-rs.github.io/docs/plugins/utils

Gets the system clipboard content when called with no arguments, or sets it when a string is provided. Available only in async context; the argument and return value are both optional strings.

```lua
-- Get contents from the clipboard if no argument is provided  

local content = ya.clipboard()  

  

-- Set contents to the clipboard  

ya.clipboard("new content")  


```

--------------------------------

### Create a Url from a path or SFTP URL

Source: https://yazi-rs.github.io/docs/plugins/types

Creates a Url object from a local file path or an SFTP URL. The first example uses a regular file path, the second uses an SFTP URL with a host and path.

```lua
-- regular file  

local url = Url("/root/Downloads/logo.png")  

  

-- `/root/dog.jpg` on `my-server` via SFTP  

local url = Url("sftp://my-server//root/dog.jpg")  

```

--------------------------------

### user_name(uid)

Source: https://yazi-rs.github.io/docs/plugins/utils

Get the username associated with a user ID.

```APIDOC
## `user_name(uid)`

### Description
Get the username by user ID. If no argument is provided, it returns the current user's name.

### Parameters
- `uid` (`integer?`) - Optional - The user ID to look up. If omitted, the current user's ID is used.

### Return Value
- `string?` - The username, or `nil` if not found.

### Availability
Unix-like systems only

### Example
```lua
-- Get the current user's name if no argument is provided
ya.user_name()

-- Get the name of user with id 1000
ya.user_name(1000)
```
```

--------------------------------

### fs.access():create(create)

Source: https://yazi-rs.github.io/docs/plugins/utils

Sets the operation to create a new file, or open it if it already exists.

```APIDOC
## fs.access():create(create)

### Description
Sets the operation to create a new file, or open it if it already exists.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
- **self** (Self) - Required - The access object.
- **create** (boolean) - Required - Whether to enable creation.

### Request Example
```lua
local access = fs.access():create(true)
```

### Response
- **Return** (self) - The access object for chaining.

```

--------------------------------

### clipboard(text)

Source: https://yazi-rs.github.io/docs/plugins/utils

Get or set the system clipboard content.

```APIDOC
## `clipboard(text)`

### Description
Get or set the content of the system clipboard. If no argument is provided, it returns the current clipboard content; otherwise, it sets the clipboard to the given text.

### Parameters
- `text` (`string?`) - Optional - The text to set to the clipboard. If omitted, the function retrieves the current clipboard content.

### Return Value
- `string?` - The current clipboard content when getting, or `nil` when setting.

### Availability
Async context only

### Example
```lua
-- Get contents from the clipboard if no argument is provided
local content = ya.clipboard()

-- Set contents to the clipboard
ya.clipboard("new content")
```
```

--------------------------------

### wait_with_output(self)

Source: https://yazi-rs.github.io/docs/plugins/utils

Waits for the child process to finish and gets its output.

```APIDOC
## wait_with_output(self)

### Description
Waits for the child process to finish and captures its output.

### Method
wait_with_output

### Parameters
- **self** (Self) - Required - The child process object.

### Return
- **Output?** - The output of the process.
- **Error?** - Error object if failed.

### Example
```lua
local output, err = child:wait_with_output()
```
```

--------------------------------

### Plugin directory structure

Source: https://yazi-rs.github.io/docs/plugins/overview

Shows the required files inside a plugin directory: main.lua, README.md, and LICENSE.

```text
~/.config/yazi/plugins/bar.yazi/  

├── main.lua  

├── README.md  

└── LICENSE  
```

--------------------------------

### group_name(gid)

Source: https://yazi-rs.github.io/docs/plugins/utils

Get the group name associated with a group ID.

```APIDOC
## `group_name(gid)`

### Description
Get the group name by group ID. If no argument is provided, it returns the current user's group name.

### Parameters
- `gid` (`integer?`) - Optional - The group ID to look up. If omitted, the current user's group ID is used.

### Return Value
- `string?` - The group name, or `nil` if not found.

### Availability
Unix-like systems only

### Example
```lua
-- Get the current user's group name if no argument is provided
ya.group_name()

-- Get the name of group with id 1000
ya.group_name(1000)
```
```

--------------------------------

### Path.parent

Source: https://yazi-rs.github.io/docs/plugins/types

Gets the parent directory of the path. Returns a Path or null if there is no parent.

```APIDOC
## Path.parent

### Description
Gets the parent directory of the path.

### Property
`parent`

### Type
`Self?`

### Returns
- `Self?` - The parent directory as a Path, or null if none.
```
Tokens:
Raw