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 uses a flexible opener system to determine which external programs should open different file types. This page explains how to configure file openers.

​
Configuration Location

File opener configuration is part of yazi.toml:
  • Unix-like systems: ~/.config/yazi/yazi.toml
  • Windows: %AppData%\yazi\config\yazi.toml

​
How Openers Work

Yazi’s opener system has two parts:
  1. [opener] - Define external programs and how to launch them
  2. [open] - Define rules that match files to openers

​
Defining Openers

Openers are defined in the [opener] section: 
[opener]
opener_name = [
  { run = "command %s", desc = "Description", ... },
  # More variants...
]

​
Opener Fields

​
run
string
required
Command to execute. Use placeholders:
  • %s - Single selected file
  • %s1 - First selected file (useful on Windows)
  • %S - All selected files (space-separated)
  • %d - Directory of selected file
  • %d1 - Directory of first selected file
  • ${EDITOR} - Environment variable
​
desc
string
required
Description shown in the opener picker
​
for
string
Platform filter. Only use this opener on matching platforms:
  • unix - All Unix-like systems
  • linux - Linux only
  • macos - macOS only
  • windows - Windows only
  • android - Android (Termux) only
​
block
boolean
default:"false"
Block the terminal until the command finishes when true
​
orphan
boolean
default:"false"
Detach the process from the terminal when true. Useful for GUI applications.

​
Example Openers

[opener]
# Text editor
edit = [
  { run = "${EDITOR:-vi} %s", desc = "$EDITOR", for = "unix", block = true },
  { run = "nvim %s", desc = "Neovim", for = "unix", block = true },
  { run = "code %s", desc = "VS Code", for = "windows", orphan = true },
]

# Generic opener
open = [
  { run = "xdg-open %s", desc = "Open", for = "linux" },
  { run = "open %s", desc = "Open", for = "macos" },
  { run = 'start "" %s1', desc = "Open", for = "windows", orphan = true },
]

# Video player
play = [
  { run = "mpv %s", desc = "MPV", orphan = true },
  { run = "vlc %s", desc = "VLC", orphan = true },
]

# Image viewer
view = [
  { run = "feh %s", desc = "Feh", for = "linux", orphan = true },
  { run = "sxiv %s", desc = "sxiv", for = "linux", orphan = true },
  { run = "Preview %s", desc = "Preview", for = "macos" },
]

# Archive extractor
extract = [
  { run = "ya pub extract --list %s", desc = "Extract here" },
]

# File manager
reveal = [
  { run = "xdg-open %d1", desc = "Reveal", for = "linux" },
  { run = "open -R %s1", desc = "Reveal", for = "macos" },
  { run = "explorer /select,%s1", desc = "Reveal", for = "windows", orphan = true },
]

​
File Opening Rules

Rules are defined in the [open] section and match files to openers: 
[open]
rules = [
  { url = "pattern", use = "opener_name" },
  { mime = "pattern", use = ["opener1", "opener2"] },
]

​
Rule Fields

​
url
string
URL pattern to match. Supports wildcards:
  • */ - Directories
  • *.txt - Files ending with .txt
  • * - All files (fallback)
​
mime
string
MIME type pattern to match. Supports wildcards:
  • text/* - All text files
  • image/* - All images
  • {audio,video}/* - Audio or video
  • application/json - Specific type
​
use
string | array
Opener(s) to use:
  • Single string: "edit"
  • Array: ["edit", "open", "reveal"] - Shows picker with options
Rules are evaluated in order. The first matching rule is used.

​
Example Rules

[open]
rules = [
  # Directories
  { url = "*/", use = ["edit", "open", "reveal"] },
  
  # Text files
  { mime = "text/*", use = ["edit", "reveal"] },
  { mime = "application/{json,ndjson}", use = ["edit", "reveal"] },
  
  # Images
  { mime = "image/*", use = ["view", "open", "reveal"] },
  
  # Videos and audio
  { mime = "{audio,video}/*", use = ["play", "reveal"] },
  
  # Archives
  { mime = "application/{zip,rar,7z*,tar,gzip}", use = ["extract", "reveal"] },
  
  # Documents
  { mime = "application/{pdf,doc}", use = ["open", "reveal"] },
  
  # Empty files
  { mime = "inode/empty", use = ["edit", "reveal"] },
  
  # Virtual filesystem
  { mime = "vfs/{absent,stale}", use = "download" },
  
  # Fallback
  { url = "*", use = ["open", "reveal"] },
]

​
Complete Example

[opener]
# Editor
edit = [
  { run = "${EDITOR:-vi} %s", desc = "$EDITOR", for = "unix", block = true },
  { run = "code %s", desc = "VS Code", orphan = true },
]

# Generic open
open = [
  { run = "xdg-open %s", desc = "Open", for = "linux" },
  { run = "open %s", desc = "Open", for = "macos" },
  { run = 'start "" %s1', desc = "Open", for = "windows", orphan = true },
]

# Media player
play = [
  { run = "mpv %s", desc = "MPV", orphan = true },
]

# Image viewer
view = [
  { run = "sxiv %s", desc = "sxiv", for = "linux", orphan = true },
]

# Extract archives
extract = [
  { run = "ya pub extract --list %s", desc = "Extract" },
]

# Reveal in file manager
reveal = [
  { run = "xdg-open %d1", desc = "Reveal", for = "linux" },
  { run = "open -R %s1", desc = "Reveal", for = "macos" },
]

[open]
rules = [
  # Directories
  { url = "*/", use = ["edit", "open", "reveal"] },
  
  # Text
  { mime = "text/*", use = ["edit", "reveal"] },
  
  # Images
  { mime = "image/*", use = ["view", "open", "reveal"] },
  
  # Media
  { mime = "{audio,video}/*", use = ["play", "reveal"] },
  
  # Archives
  { mime = "application/{zip,tar,gzip}", use = ["extract", "reveal"] },
  
  # Fallback
  { url = "*", use = ["open", "reveal"] },
]

​
Platform-Specific Configuration

You can define different openers for different platforms: 
[opener]
edit = [
  # Unix-like systems
  { run = "${EDITOR:-vi} %s", desc = "$EDITOR", for = "unix", block = true },
  { run = "nvim %s", desc = "Neovim", for = "unix", block = true },
  
  # Windows
  { run = "notepad %s", desc = "Notepad", for = "windows", block = true },
  { run = "code %s", desc = "VS Code", for = "windows", orphan = true },
  
  # macOS
  { run = "open -t %s", desc = "TextEdit", for = "macos" },
]

​
Advanced Usage

​
Multiple Files

Open multiple selected files: 
[opener]
edit_all = [
  { run = "${EDITOR:-vi} %S", desc = "Edit all", block = true },
]

​
Environment Variables

Use environment variables for flexibility: 
[opener]
edit = [
  { run = "${EDITOR:-vi} %s", desc = "$EDITOR", block = true },
  { run = "${VISUAL:-code} %s", desc = "$VISUAL", orphan = true },
]

browser = [
  { run = "${BROWSER:-firefox} %s", desc = "Browser", orphan = true },
]

​
Custom Scripts

Launch custom scripts: 
[opener]
convert = [
  { run = "~/.config/yazi/scripts/convert.sh %s", desc = "Convert", block = true },
]

​
Conditional Opening

Use MIME types to open files conditionally: 
[open]
rules = [
  # Open Markdown in editor, others in browser
  { mime = "text/markdown", use = "edit" },
  { mime = "text/html", use = "browser" },
  
  # Different viewers for different image formats
  { mime = "image/svg+xml", use = "browser" },
  { mime = "image/*", use = "view" },
]

​
Interactive Opener Selection

When multiple openers are specified in a rule, Yazi shows a picker: 
[open]
rules = [
  # User can choose between edit, open, or reveal
  { url = "*/", use = ["edit", "open", "reveal"] },
]
Press O (uppercase) or use open --interactive to force the picker even with a single opener.

​
Troubleshooting

​
Command Not Found

If an opener fails with “command not found”:
  1. Verify the program is installed
  2. Check that the program is in your PATH
  3. Use absolute paths if needed: /usr/bin/mpv %s

​
Windows Path Issues

On Windows, use %s1 instead of %s for compatibility: 
{ run = 'start "" %s1', desc = "Open", for = "windows" }

​
GUI Apps Don’t Detach

If GUI applications block the terminal, add orphan = true: 
{ run = "code %s", desc = "VS Code", orphan = true }

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us