kitty(1)

📦
version 0.49.2 · 16 versions
, in arch rolling, nixpkgs unstable

🌸 Name

Okay bestie, welcome to the kitty(1) page — aka the fast, feature rich terminal emulator. This is the manual, but make it group-chat. 💅

kitty [options] [program-to-run ...]

Run the kitty terminal emulator. You can also pass the program to run inside kitty as normal arguments after the options. For example:

kitty --hold sh -c "echo hello, world"

For the full comprehensive documentation for kitty, please see: https://sw.kovidgoyal.net/kitty/

✨ Options ✨

  • --app-id <CLS>, --class <CLS> — On Wayland this sets the application id. On X11 it sets the class part of the WM_CLASS window property. Default: kitty
  • --name <NAME>, --os-window-tag <NAME> — On Wayland this sets the window tag, when specified. On X11 this sets the name part of the WM_CLASS property; when unset, it defaults to using the value from kitty --class.
  • --title <TITLE>, -T <TITLE> — Sets the OS window title. This will override any title set by the program running inside kitty, permanently fixing the OS window’s title. So only use this if you’re running a program that does not set titles.
  • --config <CONFIG>, -c <CONFIG> — Specify a path to the configuration file(s) to use. All configuration files are merged onto the builtin kitty.conf, overriding the builtin values. This option can be specified multiple times to read multiple configuration files in sequence, which are merged. Use the special value NONE to not load any config file.

If this option is not specified, config files are searched for in the order: $XDG_CONFIG_HOME/kitty/kitty.conf, ~/.config/kitty/kitty.conf, $XDG_CONFIG_DIRS/kitty/kitty.conf. The first one that exists is used as the config file.

If the environment variable KITTY_CONFIG_DIRECTORY is specified, that directory is always used and the above searching does not happen.

If /etc/xdg/kitty/kitty.conf exists, it is merged before (i.e. with lower priority) than any user config files. It can be used to specify system-wide defaults for all users. You can use either - or /dev/stdin to read the config from STDIN.

  • --override <OVERRIDE>, -o <OVERRIDE> — Override individual configuration options. Can be specified multiple times. Syntax: name=value. For example: kitty -o font_size=20
  • --directory <DIRECTORY>, --working-directory <DIRECTORY>, -d <DIRECTORY> — Change to the specified directory when launching. Default: .
  • --detach [=no] — Detach from the controlling terminal, if any. On macOS use open -a kitty.app -n instead.
  • --detached-log <DETACHED_LOG> — Path to a log file to store STDOUT/STDERR when using --detach
  • --session <SESSION> — Path to a file containing the startup session (tabs, windows, layout, programs). Use - to read from STDIN. See Sessions for details and an example. Environment variables in the file name are expanded, relative paths are resolved relative to the kitty configuration directory. The special value none means no session will be used, even if the startup_session option has been specified in kitty.conf. Note that using this option means the command line arguments to kitty specifying a program to run are ignored.
  • --hold [=no] — Remain open, at a shell prompt, after child process exits. Note that this only affects the first window. You can quit by either using the close window shortcut or running the exit command.
  • --single-instance [=no], -1 [=no] — If specified only a single instance of kitty will run. New invocations will instead create a new top-level window in the existing kitty instance. This allows kitty to share a single sprite cache on the GPU and also reduces startup time. You can also have separate groups of kitty instances by using the kitty --instance-group option. You can use the kitty --start-as=hidden flag to start a background kitty instance that acts as a server.
  • --instance-group <INSTANCE_GROUP> — Used in combination with the kitty --single-instance option. All kitty invocations with the same kitty --instance-group will result in new windows being created in the first kitty instance within that group.
  • --wait-for-single-instance-window-close [=no] — Normally, when using kitty --single-instance, kitty will open a new window in an existing instance and quit immediately. With this option, it will not quit till the newly opened window is closed. Note that if no previous instance is found, then kitty will wait anyway, regardless of this option.
  • --listen-on <LISTEN_ON> — Listen on the specified socket address for control messages. For example, kitty --listen-on=unix:/tmp/mykitty or kitty --listen-on=tcp:localhost:12345. On Linux systems, you can also use abstract UNIX sockets, not associated with a file, like this: kitty --listen-on=unix:@mykitty. Environment variables are expanded and relative paths are resolved with respect to the temporary directory. To control kitty, you can send commands to it with kitten @ using the kitten @ --to option to specify this address. Note that if you run kitten @ within a kitty window, there is no need to specify the kitten @ --to option as it will automatically read from the environment. Note that this will be ignored unless allow_remote_control is set to either: yes, socket or socket-only. This can also be specified in kitty.conf. To start in headless mode, without an actual window, use kitty --start-as=hidden.
  • --start-as <START_AS> — Control how the initial kitty OS window is created. Note that this applies to all OS Windows if you use the kitty --session option to create multiple OS Windows. Any OS Windows state specified in the session file gets overridden. Default: normal Choices: fullscreen, hidden, maximized, minimized, normal
  • --position <POSITION> — The position, for example 10x20, on screen at which to place the first kitty OS Window created by this invocation. This may or may not work depending on the policies of the desktop environment/window manager. It never works on Wayland. See also remember_window_position to have kitty automatically try to restore the previous window position.
  • --grab-keyboard [=no] — Grab the keyboard. This means global shortcuts defined in the OS will be passed to kitty instead. Useful if you want to create an OS modal window. How well this works depends on the OS/window manager/desktop environment. On Wayland it works only if the compositor implements the inhibit-keyboard-shortcuts protocol https://wayland.app/protocols/keyboard-shortcuts-inhibit-unstable-v1. On macOS Apple doesn’t allow applications to grab the keyboard without special permissions, so it doesn’t work.

🐛 Debugging options

  • --version [=no], -v [=no] — The current kitty version.
  • --dump-commands [=no] — Output commands received from child process to STDOUT.
  • --replay-commands <REPLAY_COMMANDS> — Replay previously dumped commands. Specify the path to a dump file previously created by kitty --dump-commands. You can open a new kitty window to replay the commands with:
kitty sh -c "kitty --replay-commands /path/to/dump/file; read"
  • --dump-bytes <DUMP_BYTES> — Path to file in which to store the raw bytes received from the child process.
  • --debug-gl [=no], --debug-rendering [=no] — Debug rendering commands. This will cause all OpenGL calls to check for errors instead of ignoring them. Also prints out miscellaneous debug information. Useful when debugging rendering problems.
  • --debug-input [=no], --debug-keyboard [=no] — Print out key and mouse events as they are received.
  • --debug-font-fallback [=no] — Print out information about the selection of fallback fonts for characters not present in the main font.
  • --watcher <WATCHER> — This option is deprecated in favor of the watcher option in kitty.conf and should not be used.

🪟 Tabs and windows

kitty is capable of running multiple programs organized into tabs and windows. The top level of organization is the OS window. Each OS window consists of one or more tabs. Each tab consists of one or more kitty windows. The kitty windows can be arranged in multiple different layouts, like windows are organized in a tiling window manager. The keyboard controls (which are all customizable) for tabs and windows are:

🌸 Scrolling 🌸

okay so scrollback is literally a whole main character, and these are the key combos that let you move around it like you own the place. ✨

  • Line up — ctrl+shift+up <#shortcut-kitty.Scroll-line-up> (also ⌥+⌘+⇞ and ⌘+↑ on macOS)
  • Line down — ctrl+shift+down <#shortcut-kitty.Scroll-line-down> (also ⌥+⌘+⇟ and ⌘+↓ on macOS)
  • Page up — ctrl+shift+page_up <#shortcut-kitty.Scroll-page-up> (also ⌘+⇞ on macOS)
  • Page down — ctrl+shift+page_down <#shortcut-kitty.Scroll-page-down> (also ⌘+⇟ on macOS)
  • Top — ctrl+shift+home <#shortcut-kitty.Scroll-to-top> (also ⌘+↖ on macOS)
  • Bottom — ctrl+shift+end <#shortcut-kitty.Scroll-to-bottom> (also ⌘+↘ on macOS)
  • Previous shell prompt — ctrl+shift+z <#shortcut-kitty.Scroll-to-previous-shell-prompt> (see Shell integration <#shell-integration>)
  • Next shell prompt — ctrl+shift+x <#shortcut-kitty.Scroll-to-next-shell-prompt> (see Shell integration <#shell-integration>)
  • Browse scrollback in less — ctrl+shift+h <#shortcut-kitty.Browse-scrollback-buffer-in-pager>
  • Browse last cmd output — ctrl+shift+g <#shortcut-kitty.Browse-output-of-the-last-shell-command-in-pager> (see Shell integration <#shell-integration>)
  • Search scrollback in less — ctrl+shift+/ <#shortcut-kitty.Search-the-scrollback-within-a-pager> (also ⌘+F on macOS)
heads up bestie: these scroll actions only take effect when the terminal is in the main screen. when the alternate screen is active (for example when using a full screen program like an editor) the key events are instead passed to the program running in the terminal. 💅

🎀 Tabs 🎀

tabs are lowkey self-care, no cap. here’s the whole tab situation so you can shuffle them around with main character energy. 🦋

  • New tab — ctrl+shift+t <#shortcut-kitty.New-tab> (also ⌘+t on macOS)
  • Close tab — ctrl+shift+q <#shortcut-kitty.Close-tab> (also ⌘+w on macOS)
  • Next tab — ctrl+shift+right <#shortcut-kitty.Next-tab> (also ⌃+⇥ and ⇧+⌘+] on macOS)
  • Previous tab — ctrl+shift+left <#shortcut-kitty.Previous-tab> (also ⇧+⌃+⇥ and ⇧+⌘+[ on macOS)
  • Next layout — ctrl+shift+l <#shortcut-kitty.Next-layout>
  • Move tab forward — ctrl+shift+. <#shortcut-kitty.Move-tab-forward>
  • Move tab backward — ctrl+shift+, <#shortcut-kitty.Move-tab-backward>
  • Set tab title — ctrl+shift+alt+t <#shortcut-kitty.Set-tab-title> (also ⇧+⌘+i on macOS)

tab management is literally a vibe, periodt. 💖

🪟 windows, but make it window management 💖

okay so here's the whole window situation, shortcut by shortcut. each one also has a named action you can bind to whatever you want — the #shortcut-kitty. thing is the action's name, iykyk.

  • new window — ctrl+shift+enter (#shortcut-kitty.New-window), and it's also ⌘+↩ on macOS ✨
  • new OS window — ctrl+shift+n (#shortcut-kitty.New-OS-window), plus ⌘+n on macOS 🦋
  • close window — ctrl+shift+w (#shortcut-kitty.Close-window), plus ⇧+⌘+d on macOS 💅
  • resize window — ctrl+shift+r (#shortcut-kitty.Start-resizing-window), plus ⌘+r on macOS
  • next window — ctrl+shift+] (#shortcut-kitty.Next-window)
  • previous window — ctrl+shift+[ (#shortcut-kitty.Previous-window)
  • move window forward — ctrl+shift+f (#shortcut-kitty.Move-window-forward)
  • move window backward — ctrl+shift+b (#shortcut-kitty.Move-window-backward)
  • move window to top — ctrl+shift+` (#shortcut-kitty.Move-window-to-top)
  • visually focus window — ctrl+shift+f7 (#shortcut-kitty.Visually-select-and-focus-window)
  • visually swap window — ctrl+shift+f8 (#shortcut-kitty.Visually-swap-window-with-another)
  • focus specific window — ctrl+shift+1 (#shortcut-kitty.First-window), ctrl+shift+2 (#shortcut-kitty.Second-window) ... ctrl+shift+0 (#shortcut-kitty.Tenth-window), also ⌘+1, ⌘+2 ... ⌘+9 on macOS 🎀 (they go clockwise from the top-left, cute right?)

and bestie, there's MORE 🌈 you can define your own shortcuts in kitty.conf to focus neighbouring windows and move windows around — literally vim window movement vibes, obsessed:

map ctrl+left neighboring_window left
map shift+left move_window right
map ctrl+down neighboring_window down
map shift+down move_window up
...

want to hop back to the window you were just in? yes queen, there's a shortcut for that too:

map ctrl+p nth_window -1

so nth_window (#action-nth_window) focuses the nth window when you give it a positive number (counting starts from zero, no cap) and the previously active window when the number is negative. time travel but make it terminal 💜

and for the OS-window girlies, define nth_os_window (#action-nth_os_window). heads up though: only positive numbers are accepted here, and it starts from one 🫶

you can also make shortcuts that detach the current window and yeet it into another tab or another OS window:

# moves the window into a new OS window
map ctrl+f2 detach_window
# moves the window into a new tab
map ctrl+f3 detach_window new-tab
# moves the window into the previously active tab
map ctrl+f3 detach_window tab-prev
# moves the window into the tab at the left of the active tab
map ctrl+f3 detach_window tab-left
# moves the window into a new tab created to the left of the active tab
map ctrl+f3 detach_window new-tab-left
# asks which tab to move the window into
map ctrl+f4 detach_window ask

same energy for tabs, you can detach the whole current tab:

# moves the tab into a new OS window
map ctrl+f2 detach_tab
# asks which OS Window to move the tab into
map ctrl+f4 detach_tab ask
✨ pro tip from the manpage: tabs can be re-arranged, detached and moved to another OS Window in the same kitty instance using drag and drop. drag and drop!! main character behaviour 💅

finally, if you want a shortcut that closes every window in the tab except the one you're on (iconic, slightly savage):

map f9 close_other_windows_in_tab

⌨️ Other keyboard shortcuts ⌨️

okay bestie, so there are so many more key combos than the ones we already covered, and the full list of actions you can map to key presses is available here <>. and if you wanna learn how to do more sophisticated keyboard mappings — modal mappings, per-application mappings, all that spicy stuff — go read Making your keyboard dance <>. ✨

here's the iconic shortcut cheat sheet, fr fr:

  • Show this help — ctrl+shift+f1 <#> (that's shortcut-kitty.Show-documentation)
  • Copy to clipboard — ctrl+shift+c <#> (shortcut-kitty.Copy-to-clipboard) — also ⌘+c on macOS 🍓
  • Paste from clipboard — ctrl+shift+v <#> (shortcut-kitty.Paste-from-clipboard) — also ⌘+v on macOS 🍓
  • Paste from selection — ctrl+shift+s <#> (shortcut-kitty.Paste-from-selection)
  • Pass selection to program — ctrl+shift+o <#> (shortcut-kitty.Pass-selection-to-program)
  • Increase font size — ctrl+shift+equal <#> (shortcut-kitty.Increase-font-size) — also ⌘++ on macOS 🍓
  • Decrease font size — ctrl+shift+minus <#> (shortcut-kitty.Decrease-font-size) — also ⌘+- on macOS 🍓
  • Restore font size — ctrl+shift+backspace <#> (shortcut-kitty.Reset-font-size) — also ⌘+0 on macOS 🍓
  • Toggle fullscreen — ctrl+shift+f11 <#> (shortcut-kitty.Toggle-fullscreen) — also ⌃+⌘+f on macOS 🍓
  • Toggle maximized — ctrl+shift+f10 <#> (shortcut-kitty.Toggle-maximized)
  • Input Unicode character — ctrl+shift+u <#> (shortcut-kitty.Unicode-input) — also ⌃+⌘+space on macOS 🍓
  • Open URL in web browser — ctrl+shift+e <#> (shortcut-kitty.Open-URL)
  • Reset the terminal — ctrl+shift+delete <#> (shortcut-kitty.Reset-the-terminal) — also ⌥+⌘+r on macOS 🍓
  • Edit kitty.conf — ctrl+shift+f2 <#> (shortcut-kitty.Edit-config-file) — also ⌘+, on macOS 🍓
  • Reload kitty.conf — ctrl+shift+f5 <#> (shortcut-kitty.Reload-kitty.conf) — also ⌃+⌘+, on macOS 🍓
  • Debug kitty.conf — ctrl+shift+f6 <#> (shortcut-kitty.Debug-kitty-configuration) — also ⌥+⌘+, on macOS 🍓
  • Open a kitty shell — ctrl+shift+escape <#> (shortcut-kitty.Open-the-kitty-command-shell)
  • Increase background opacity — ctrl+shift+a>m <#> (shortcut-kitty.Increase-background-opacity)
  • Decrease background opacity — ctrl+shift+a>l <#> (shortcut-kitty.Decrease-background-opacity)
  • Full background opacity — ctrl+shift+a>1 <#> (shortcut-kitty.Make-background-fully-opaque)
  • Reset background opacity — ctrl+shift+a>d <#> (shortcut-kitty.Reset-background-opacity)

the way that background-opacity chord is giving two-step combo energy, iykyk 💅

👀 See also

✍️ Author

Kovid Goyal 👑

2026, Kovid Goyal

and that's the whole page, bestie!! 🎀 this was kitty version 0.49.2, dated Oct 01, 2026 — go forth and slay your terminal, no cap 💖✨🦋

📦 where this page comes from