> ## 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.
# 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:
```bash theme={null}
~/.config/yazi/
```
```bash theme={null}
%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:
```bash theme={null}
mkdir -p ~/.config/yazi
```
2. Create your configuration file(s):
```bash theme={null}
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:
```toml theme={null}
[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:
```toml theme={null}
[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:
```toml theme={null}
[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:
```toml theme={null}
"$schema" = "https://yazi-rs.github.io/schemas/yazi.json"
```
You can use a TOML linter like [taplo](https://taplo.tamasfe.dev/) 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](https://github.com/sxyazi/yazi/tree/shipped/yazi-config/preset) in the Yazi repository
2. Look at the configuration pages in this documentation
3. Run Yazi with default configuration and inspect behavior
## Next Steps
Configure the file manager behavior
Customize keybindings
Customize colors and appearance
Configure virtual filesystem services