> ## 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.

# 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:

```toml theme={null}
[opener]
opener_name = [
  { run = "command %s", desc = "Description", ... },
  # More variants...
]
```

### Opener Fields

<ParamField path="run" type="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
</ParamField>

<ParamField path="desc" type="string" required>
  Description shown in the opener picker
</ParamField>

<ParamField path="for" type="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
</ParamField>

<ParamField path="block" type="boolean" default="false">
  Block the terminal until the command finishes when `true`
</ParamField>

<ParamField path="orphan" type="boolean" default="false">
  Detach the process from the terminal when `true`. Useful for GUI applications.
</ParamField>

### Example Openers

```toml theme={null}
[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:

```toml theme={null}
[open]
rules = [
  { url = "pattern", use = "opener_name" },
  { mime = "pattern", use = ["opener1", "opener2"] },
]
```

### Rule Fields

<ParamField path="url" type="string">
  URL pattern to match. Supports wildcards:

  * `*/` - Directories
  * `*.txt` - Files ending with .txt
  * `*` - All files (fallback)
</ParamField>

<ParamField path="mime" type="string">
  MIME type pattern to match. Supports wildcards:

  * `text/*` - All text files
  * `image/*` - All images
  * `{audio,video}/*` - Audio or video
  * `application/json` - Specific type
</ParamField>

<ParamField path="use" type="string | array">
  Opener(s) to use:

  * Single string: `"edit"`
  * Array: `["edit", "open", "reveal"]` - Shows picker with options
</ParamField>

<Note>
  Rules are evaluated in order. The first matching rule is used.
</Note>

### Example Rules

```toml theme={null}
[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

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[opener]
edit_all = [
  { run = "${EDITOR:-vi} %S", desc = "Edit all", block = true },
]
```

### Environment Variables

Use environment variables for flexibility:

```toml theme={null}
[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:

```toml theme={null}
[opener]
convert = [
  { run = "~/.config/yazi/scripts/convert.sh %s", desc = "Convert", block = true },
]
```

### Conditional Opening

Use MIME types to open files conditionally:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
{ run = 'start "" %s1', desc = "Open", for = "windows" }
```

### GUI Apps Don't Detach

If GUI applications block the terminal, add `orphan = true`:

```toml theme={null}
{ run = "code %s", desc = "VS Code", orphan = true }
```

## See Also

* [Yazi Configuration](configuration/yazi)
* [VFS Configuration](configuration/vfs)
* [File Type Detection](configuration/theme#filetype---file-type-colors)