keymap.toml

Customize Yazi’s keybindings for file management and navigation

The keymap.toml file defines all keybindings in Yazi. You can customize existing keybindings or add new ones.

File Location

• Unix-like systems: ~/.config/yazi/keymap.toml
• Windows: %AppData%\yazi\config\keymap.toml

Keymap Structure

The keymap file is organized by UI layer. Each layer represents a different part of the interface:

[mgr]      # File manager
[tasks]    # Task manager
[spot]     # File details (spotter)
[pick]     # Picker dialogs
[input]    # Input dialogs
[confirm]  # Confirmation dialogs
[help]     # Help menu
[cmp]      # Completion popup

Keymap Entry Format

Each keybinding is defined as a table in an array:

[[mgr.keymap]]
on = "<key>"
run = "command"
desc = "Description"

Or more concisely:

{ on = "<key>", run = "command", desc = "Description" }

Fields

on · string | array · required

The key(s) to bind. Can be a single key or an array for key sequences.

Examples:

• "j" - Single key
• "<C-c>" - Control+C
• ["g", "g"] - Key sequence: press ‘g’ twice

run · string | array · required

The command(s) to execute. Can be a single command or array of commands.

Examples:

• "arrow next" - Single command
• ["toggle", "arrow 1"] - Multiple commands

desc · string

Description shown in help menu and which-key popup

Key Syntax

Basic Keys

Alphanumeric and symbol keys:

on = "a"      # Letter a
on = "1"      # Number 1
on = "-"      # Dash
on = "."      # Period

Special Keys

Special keys use angle brackets:

on = "<Esc>"      # Escape
on = "<Enter>"    # Enter/Return
on = "<Tab>"      # Tab
on = "<Space>"    # Space
on = "<Backspace>" # Backspace
on = "<Delete>"   # Delete

on = "<Up>"       # Arrow up
on = "<Down>"     # Arrow down
on = "<Left>"     # Arrow left
on = "<Right>"    # Arrow right

on = "<PageUp>"   # Page Up
on = "<PageDown>" # Page Down
on = "<Home>"     # Home
on = "<End>"      # End

on = "<F1>"       # Function keys
on = "<F2>"

Modifiers

Modifiers are specified with angle brackets:

on = "<C-c>"      # Ctrl+C
on = "<A-a>"      # Alt+A (Meta on some systems)
on = "<S-PageUp>" # Shift+PageUp
on = "<C-A-d>"    # Ctrl+Alt+D

• <C-> = Control/Ctrl
• <A-> = Alt/Option/Meta
• <S-> = Shift

Key Sequences

Define multi-key sequences with arrays:

on = ["g", "g"]    # Press 'g' twice
on = ["c", "c"]    # Press 'c' twice
on = [",", "m"]    # Press ',' then 'm'

Manager Layer [mgr]

The main file manager keybindings.

Navigation

[[mgr.keymap]]
on = "j"
run = "arrow next"
desc = "Next file"

[[mgr.keymap]]
on = "k"
run = "arrow prev"
desc = "Previous file"

[[mgr.keymap]]
on = "h"
run = "leave"
desc = "Back to parent directory"

[[mgr.keymap]]
on = "l"
run = "enter"
desc = "Enter directory"

[[mgr.keymap]]
on = ["g", "g"]
run = "arrow top"
desc = "Go to top"

[[mgr.keymap]]
on = "G"
run = "arrow bot"
desc = "Go to bottom"

Selection

[[mgr.keymap]]
on = "<Space>"
run = ["toggle", "arrow 1"]
desc = "Toggle selection"

[[mgr.keymap]]
on = "<C-a>"
run = "toggle_all --state=on"
desc = "Select all"

[[mgr.keymap]]
on = "<C-r>"
run = "toggle_all"
desc = "Invert selection"

[[mgr.keymap]]
on = "v"
run = "visual_mode"
desc = "Enter visual mode"

File Operations

[[mgr.keymap]]
on = "y"
run = "yank"
desc = "Copy files"

[[mgr.keymap]]
on = "x"
run = "yank --cut"
desc = "Cut files"

[[mgr.keymap]]
on = "p"
run = "paste"
desc = "Paste files"

[[mgr.keymap]]
on = "d"
run = "remove"
desc = "Move to trash"

[[mgr.keymap]]
on = "D"
run = "remove --permanently"
desc = "Delete permanently"

[[mgr.keymap]]
on = "a"
run = "create"
desc = "Create file/directory"

[[mgr.keymap]]
on = "r"
run = "rename --cursor=before_ext"
desc = "Rename file"

Opening Files

[[mgr.keymap]]
on = "o"
run = "open"
desc = "Open file"

[[mgr.keymap]]
on = "O"
run = "open --interactive"
desc = "Open with picker"

[[mgr.keymap]]
on = "<Enter>"
run = "open"
desc = "Open file"

Search and Filter

[[mgr.keymap]]
on = "s"
run = "search --via=fd"
desc = "Search by name"

[[mgr.keymap]]
on = "S"
run = "search --via=rg"
desc = "Search by content"

[[mgr.keymap]]
on = "f"
run = "filter --smart"
desc = "Filter files"

[[mgr.keymap]]
on = "/"
run = "find --smart"
desc = "Find next"

[[mgr.keymap]]
on = "?"
run = "find --previous --smart"
desc = "Find previous"

Sorting

[[mgr.keymap]]
on = [",", "m"]
run = ["sort mtime --reverse=no", "linemode mtime"]
desc = "Sort by modified time"

[[mgr.keymap]]
on = [",", "M"]
run = ["sort mtime --reverse=yes", "linemode mtime"]
desc = "Sort by modified time (reverse)"

[[mgr.keymap]]
on = [",", "s"]
run = ["sort size --reverse=no", "linemode size"]
desc = "Sort by size"

[[mgr.keymap]]
on = [",", "a"]
run = "sort alphabetical --reverse=no"
desc = "Sort alphabetically"

Input Layer [input]

Input dialog keybindings (for rename, create, etc.).

[[input.keymap]]
on = "<Enter>"
run = "close --submit"
desc = "Submit input"

[[input.keymap]]
on = "<Esc>"
run = "escape"
desc = "Cancel input"

[[input.keymap]]
on = "i"
run = "insert"
desc = "Enter insert mode"

[[input.keymap]]
on = "a"
run = "insert --append"
desc = "Enter append mode"

[[input.keymap]]
on = "v"
run = "visual"
desc = "Enter visual mode"

# Vim-like movement
[[input.keymap]]
on = "h"
run = "move -1"
desc = "Move left"

[[input.keymap]]
on = "l"
run = "move 1"
desc = "Move right"

[[input.keymap]]
on = "0"
run = "move bol"
desc = "Move to beginning"

[[input.keymap]]
on = "$"
run = "move eol"
desc = "Move to end"

Tasks Layer [tasks]

Task manager keybindings.

[[tasks.keymap]]
on = "<Esc>"
run = "close"
desc = "Close task manager"

[[tasks.keymap]]
on = "w"
run = "close"
desc = "Close task manager"

[[tasks.keymap]]
on = "k"
run = "arrow prev"
desc = "Previous task"

[[tasks.keymap]]
on = "j"
run = "arrow next"
desc = "Next task"

[[tasks.keymap]]
on = "<Enter>"
run = "inspect"
desc = "Inspect task"

[[tasks.keymap]]
on = "x"
run = "cancel"
desc = "Cancel task"

Confirm Layer [confirm]

Confirmation dialog keybindings.

[[confirm.keymap]]
on = "<Enter>"
run = "close --submit"
desc = "Confirm"

[[confirm.keymap]]
on = "<Esc>"
run = "close"
desc = "Cancel"

[[confirm.keymap]]
on = "y"
run = "close --submit"
desc = "Yes"

[[confirm.keymap]]
on = "n"
run = "close"
desc = "No"

Complete Example

"$schema" = "https://yazi-rs.github.io/schemas/keymap.json"

# File Manager
[[mgr.keymap]]
on = "j"
run = "arrow next"
desc = "Next file"

[[mgr.keymap]]
on = "k"
run = "arrow prev"
desc = "Previous file"

[[mgr.keymap]]
on = "<Space>"
run = ["toggle", "arrow 1"]
desc = "Toggle selection"

[[mgr.keymap]]
on = "y"
run = "yank"
desc = "Copy"

[[mgr.keymap]]
on = "p"
run = "paste"
desc = "Paste"

# Task Manager
[[tasks.keymap]]
on = "w"
run = "close"
desc = "Close"

# Input Dialog
[[input.keymap]]
on = "<Enter>"
run = "close --submit"
desc = "Submit"

[[input.keymap]]
on = "<Esc>"
run = "escape"
desc = "Cancel"

Tips

Override Default Keybindings

You don’t need to copy all default keybindings. Just specify the ones you want to change:

# Change only 'j' and 'k' to arrow keys
[[mgr.keymap]]
on = "<Down>"
run = "arrow next"
desc = "Next file"

[[mgr.keymap]]
on = "<Up>"
run = "arrow prev"
desc = "Previous file"

Multiple Commands

Execute multiple commands in sequence:

[[mgr.keymap]]
on = "<Space>"
run = [
  "toggle",      # Toggle selection
  "arrow 1"      # Move down one
]
desc = "Toggle and move"

Command Arguments

Many commands accept arguments:

# Move cursor
run = "arrow 5"          # Move down 5 lines
run = "arrow -3"         # Move up 3 lines
run = "arrow 50%"        # Move down 50%
run = "arrow -100%"      # Move up one page

# Sort
run = "sort mtime --reverse=yes"
run = "sort size --reverse=no"

# Open
run = "open"                    # Use default opener
run = "open --interactive"      # Show opener picker

# Rename
run = "rename --cursor=before_ext"  # Position cursor before extension
run = "rename --cursor=end"         # Position cursor at end

See Also

• Commands Reference
• Yazi Configuration
• Theme Configuration