kitty(1) kitty kitty(1)
Name
kitty - The fast, feature rich terminal emulator
kitty [options] [program-to-run ...]
Run the kitty terminal emulator. You can also specify the program to
run inside kitty as normal arguments following the options. For
example: kitty --hold sh -c "echo hello, world"
For comprehensive documentation for kitty, please see:
Options
--app-id , --class
On Wayland set the application id. On X11 set the class part of
the WM_CLASS window property. Default: kitty
--name , --os-window-tag
On Wayland, set the window tag, when specified. On X11, set the
name part of the WM_CLASS property, when unset, defaults to
using the value from kitty --class.
--title , -T <TITLE>
Set 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 are 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 <#envvar-
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 <#
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 <#
opt-kitty.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.
--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 <#cmdoption-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 <#cmdoption-kitten-to> option as it will automatically read
from the environment. Note that this will be ignored unless
allow_remote_control <#opt-kitty.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 is 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 overriden. 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. 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 <#opt-kitty
.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 <#opt-kitty
.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 <#term-
os_window>. Each OS window consists of one or more tabs <#term-tab>.
Each tab consists of one or more kitty windows <#term-window>. The
kitty windows can be arranged in multiple different layouts <#term-
layout>, like windows are organized in a tiling window manager. The
keyboard controls (which are all customizable <#conf-kitty-shortcuts>)
for tabs and windows are:
Scrolling
+--------------------------+--------------------------------------------------------------------+
|Action | Shortcut |
+--------------------------+--------------------------------------------------------------------+
|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 <?>+v 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) |
+--------------------------+--------------------------------------------------------------------+
The 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 program running in the terminal.
Tabs
+------------------+-------------------------------------+
|Action | Shortcut |
+------------------+-------------------------------------+
|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) |
+------------------+-------------------------------------+
Windows
+----------------------+-----------------------------------------------------+
|Action | Shortcut |
+----------------------+-----------------------------------------------------+
|New window | ctrl+shift+enter <#shortcut-kitty.New-window> (also |
| | <?>+<?> on macOS) |
+----------------------+-----------------------------------------------------+
|New OS window | ctrl+shift+n <#shortcut-kitty.New-OS-window> (also |
| | <?>+n on macOS) |
+----------------------+-----------------------------------------------------+
|Close window | ctrl+shift+w <#shortcut-kitty.Close-window> (also |
| | <?>+<?>+d on macOS) |
+----------------------+-----------------------------------------------------+
|Resize window | ctrl+shift+r <#shortcut-kitty |
| | .Start-resizing-window> (also <?>+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) (clockwise from |
| | the top-left) |
+----------------------+-----------------------------------------------------+
Additionally, you can define shortcuts in kitty.conf to focus
neighboring windows and move windows around (similar to window movement
in vim):
map ctrl+left neighboring_window left
map shift+left move_window right
map ctrl+down neighboring_window down
map shift+down move_window up
...
You can also define a shortcut to switch to the previously active
window:
map ctrl+p nth_window -1
nth_window <#action-nth_window> will focus the nth window for positive
numbers (starting from zero) and the previously active windows for
negative numbers.
To switch to the nth OS window, you can define nth_os_window <#action-
nth_os_window>. Only positive numbers are accepted, starting from one.
You can define shortcuts to detach the current window and move it to
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
Similarly, you can detach the current tab, with:
# 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
Finally, you can define a shortcut to close all windows in a tab other
than the currently active window:
map f9 close_other_windows_in_tab
Other keyboard shortcuts
The full list of actions that can be mapped to key presses is available
here <>. To learn how to do more sophisticated keyboard mappings, such
as modal mappings, per application mappings, etc. see Making your
keyboard dance <>.
+--------------------------+------------------------------------------------+
|Action | Shortcut |
+--------------------------+------------------------------------------------+
|Show this help | ctrl+shift+f1 <#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 | ctrl+shift+a>m <#shortcut-kitty |
|opacity | .Increase-background-opacity> |
+--------------------------+------------------------------------------------+
|Decrease background | ctrl+shift+a>l <#shortcut-kitty |
|opacity | .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> |
+--------------------------+------------------------------------------------+
See also
See kitty.conf(5)
Author
Kovid Goyal
Copyright
2025, Kovid Goyal
0.45.0 December 24, 2025 kitty(1)