File Openers

Configure how Yazi opens different file types with external programs

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

• Yazi Configuration
• VFS Configuration
• File Type Detection