Configuration Overview

Learn about Yazi’s configuration system, file locations, and loading order

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:

File	Purpose
yazi.toml	General configuration (manager, preview, opener, tasks, etc.)
keymap.toml	Keybinding configuration
theme.toml	Color scheme and visual customization
vfs.toml	Virtual filesystem service configuration

Configuration Directory

Yazi looks for configuration files in the following locations:

Unix-like (Linux, macOS)

~/.config/yazi/

Windows

%AppData%\yazi\config\

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