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 TOML files for configuration. This page explains where configuration files are located, how they’re structured, and how Yazi loads them.

​
Configuration Files

Yazi uses the following configuration files:
FilePurpose
yazi.tomlGeneral configuration (manager, preview, opener, tasks, etc.)
keymap.tomlKeybinding configuration
theme.tomlColor scheme and visual customization
vfs.tomlVirtual filesystem service configuration

​
Configuration Directory

Yazi looks for configuration files in the following locations: 
~/.config/yazi/

​
Default Configuration

Yazi includes default configuration files that are used when user configuration files don’t exist:
  • yazi-default.toml - Default general configuration
  • keymap-default.toml - Default keybindings
  • theme-dark.toml - Default dark color scheme
  • theme-light.toml - Default light color scheme
  • vfs-default.toml - Default VFS service configuration
These files are embedded in Yazi and don’t need to be manually downloaded.

​
Configuration Loading Order

Yazi loads configuration in the following order:
  1. Load defaults - Yazi starts with built-in default configurations
  2. Merge user config - User configuration files override specific settings
  3. Validate - Yazi validates the merged configuration
  4. Apply - The final configuration is applied
You only need to specify the settings you want to override in your user configuration files. All unspecified settings will use the default values.

​
Creating Configuration Files

To customize Yazi’s configuration:
  1. Create the configuration directory if it doesn’t exist: 
    mkdir -p ~/.config/yazi
  2. Create your configuration file(s): 
    touch ~/.config/yazi/yazi.toml
touch ~/.config/yazi/keymap.toml
touch ~/.config/yazi/theme.toml
  3. Add your custom configuration using TOML syntax

​
Configuration Structure

​
yazi.toml Structure

The yazi.toml file is organized into sections: 
[mgr]        # Manager/file browser settings
[preview]    # Preview pane settings
[opener]     # External program definitions
[open]       # File opening rules
[tasks]      # Background task settings
[plugin]     # Plugin configuration
[input]      # Input dialog settings
[confirm]    # Confirmation dialog settings
[pick]       # Picker dialog settings
[which]      # Which-key popup settings

​
keymap.toml Structure

The keymap.toml file is organized by UI layer: 
[mgr]        # File manager keybindings
[tasks]      # Task manager keybindings
[spot]       # Spotter (file details) keybindings
[pick]       # Picker keybindings
[input]      # Input dialog keybindings
[confirm]    # Confirmation dialog keybindings
[help]       # Help menu keybindings
[cmp]        # Completion keybindings

​
theme.toml Structure

The theme.toml file defines visual appearance: 
[flavor]     # Light/dark mode flavor selection
[app]        # Overall app styling
[mgr]        # Manager styling
[tabs]       # Tab bar styling
[mode]       # Mode indicator styling
[indicator]  # File indicator styling
[status]     # Status bar styling
[which]      # Which-key popup styling
[confirm]    # Confirmation dialog styling
[spot]       # Spotter styling
[notify]     # Notification styling
[pick]       # Picker styling
[input]      # Input dialog styling
[cmp]        # Completion styling
[tasks]      # Task manager styling
[help]       # Help menu styling
[filetype]   # File type colors
[icon]       # File/folder icons

​
Schema Validation

Yazi provides JSON schemas for configuration validation: 
"$schema" = "https://yazi-rs.github.io/schemas/yazi.json"
You can use a TOML linter like taplo to validate your configuration files.

​
Version Compatibility

If you’re using a stable release of Yazi instead of the nightly build, make sure to reference the configuration documentation and default files from the shipped tag, not the main branch.
Configuration format may change between versions. Always check the documentation for your specific Yazi version.

​
Troubleshooting

​
Configuration Not Loading

If your configuration isn’t being applied:
  1. Check the file location matches your OS
  2. Ensure the filename is correct (e.g., yazi.toml, not yazi.conf)
  3. Validate TOML syntax using a linter
  4. Check Yazi’s error messages for validation errors

​
Syntax Errors

Common TOML syntax issues:
  • Missing quotes around strings with special characters
  • Incorrect array syntax (use [] not {})
  • Unclosed brackets or quotes
  • Invalid table names

​
Finding Default Values

To see default configuration values:
  1. Check the preset directory in the Yazi repository
  2. Look at the configuration pages in this documentation
  3. Run Yazi with default configuration and inspect behavior

​
Next Steps

Yazi Configuration

Configure the file manager behavior

Keymap Configuration

Customize keybindings

Theme Configuration

Customize colors and appearance

VFS Configuration

Configure virtual filesystem services

Build docs developers (and LLMs) love

Get started for freeTalk to us