Skip to main content

Viewing and Modifying Kitty Keyboard Shortcuts

Kitty’s keyboard shortcuts are explicit and configurable, but AFAIK they are not exposed via a traditional in-terminal “help panel” like tmux. Instead, kitty relies on configuration files and generated documentation.

This article explains the actual, correct ways to:

  1. View existing kitty keyboard shortcuts
  2. Modify or add your own shortcuts
  3. Debug key behavior when needed

1. Viewing Kitty Keyboard Shortcuts​

1.1 The shipped example config — and why grepping it disappoints​

Kitty ships an example config with the package:

/usr/share/doc/kitty/examples/kitty.conf

The advice you'll find everywhere is to grep it for bindings:

grep '^map ' /usr/share/doc/kitty/examples/kitty.conf

This returns nothing. Not on a misconfigured system — on any system. The file is entirely commented out. On kitty 0.41.1 it has 2714 lines and zero uncommented directives:

$ grep -vcE '^\s*(#|$)' /usr/share/doc/kitty/examples/kitty.conf
0

Every binding in that file is documentation, prefixed with #:. To see them you have to grep the comments, not the config:

grep -E '^#: +map ' /usr/share/doc/kitty/examples/kitty.conf
#:     map alt+1 disable_ligatures_in active always
#:     map alt+2 disable_ligatures_in all never
#:     map ctrl+shift+f2 edit_config_file

Be aware of what that gets you: 19 illustrative examples, not the default keymap. These are the bindings the docs chose to demonstrate syntax with. The real defaults are compiled into kitty and are not in this file at all.

So the example config is useful for discovering what actions exist and how the syntax works. It is not a list of your shortcuts, and treating it as one is the most common mistake here.

1.2 Browser-based help (generated from your active config)​

Inside a kitty window, press:

Ctrl + Shift + F1

This generates an HTML help page and opens it in your default web browser.

What it shows:

  • Active keybindings
  • Defaults plus your overrides
  • Generated from your running configuration

Notes:

  • This opens outside the terminal
  • It is accurate, but involves a context switch
  • Useful for browsing, not ideal as a primary reference

1.3 What does not exist (important clarification)​

There is no built-in kitten that lists all keybindings in-terminal.

Specifically, commands like:

kitty +kitten show_keybindings

do not exist and will fail.

Kitty does not provide a TUI or CLI command that prints the full active keymap.

2. Debugging Key Input (Advanced)​

Kitty does provide a diagnostic tool for inspecting raw key events:

kitty +kitten show_key

This does not show shortcuts.

Instead, it displays:

  • The raw key events kitty receives
  • Escape sequences
  • Modifier states

Use this only when:

  • Writing custom keybindings
  • Debugging unexpected behavior
  • Investigating how a key combo is interpreted

Exit with:

Ctrl + D

3. Modifying Kitty Keyboard Shortcuts​

All keyboard customization happens in one file:

~/.config/kitty/kitty.conf

Create it if needed:

mkdir -p ~/.config/kitty
nano ~/.config/kitty/kitty.conf

3.1 Basic keybinding syntax​

map <key-combo> <action>

Example:

map ctrl+shift+o copy_last_cmd_output

This binds:

Ctrl + Shift + O

to copying the previous command’s output.

3.2 Overriding default shortcuts​

Redefining a key automatically overrides the default.

Example:

map ctrl+shift+h show_scrollback

No explicit “disable” step is required.

3.3 Unbinding a shortcut​

To disable a default binding:

map ctrl+shift+t noop

This is useful for removing features you don’t use (tabs, layouts, etc.).

3.4 Discovering available actions​

Actions you can bind are listed in the example config file:

/usr/share/doc/kitty/examples/kitty.conf

Search for:

# Actions

Common examples include:

  • copy_to_clipboard
  • paste_from_clipboard
  • show_scrollback
  • copy_last_cmd_output
  • new_window
  • close_window

If an action exists, it’s documented there.

4. Applying changes​

After editing kitty.conf:

  • Close all kitty windows
  • Relaunch kitty

Kitty reads its configuration at startup.

To keep things sane:

  • Treat the example config as the source of truth
  • Use browser help for occasional browsing
  • Use show_key only for debugging
  • Keep your custom bindings minimal and intentional

Kitty favors explicit configuration over runtime introspection.

TL;DR​

  • There is no in-terminal keybinding viewer
  • grep '^map ' /usr/share/doc/kitty/examples/kitty.conf returns nothing — that file is 100% comments. Grep '^#: +map ' if you want the 19 documented examples, but they aren't your defaults
  • Ctrl + Shift + F1 is the only thing that shows your actual active keymap, defaults plus overrides — and it opens a browser
  • kitty +kitten show_key is for debugging key events, not listing shortcuts
  • Modify bindings via ~/.config/kitty/kitty.conf

Comments

No comments yet. Be the first!