1KITTY.CONF(5) kitty KITTY.CONF(5)
2
6 kitty.conf - kitty terminal emulator configuration file
7
9 kitty is highly customizable, everything from keyboard shortcuts, to
10 rendering frames-per-second. See below for an overview of all cus‐
11 tomization possibilities.
12 You can open the config file within kitty by pressing ctrl+shift+f2
14 (⌘+, on macOS). A kitty.conf with commented default configurations and
15 descriptions will be created if the file does not exist. You can
16 reload the config file within kitty by pressing ctrl+shift+f5 (⌃+⌘+, on
17 macOS) or sending kitty the SIGUSR1 signal. You can also display the
18 current configuration by pressing ctrl+shift+f6 (⌥+⌘+, on macOS).
19 kitty looks for a config file in the OS config directories (usually
21 ~/.config/kitty/kitty.conf) but you can pass a specific path via the
22 kitty --config option or use the KITTY_CONFIG_DIRECTORY environment
23 variable. See kitty --config for full details.
24 Comments can be added to the config file as lines starting with the #
26 character. This works only if the # character is the first character in
27 the line.
28 Lines can be split by starting the next line with the \ character. All
30 leading whitespace and the \ character are removed.
31 You can include secondary config files via the include directive. If
33 you use a relative path for include, it is resolved with respect to the
34 location of the current config file. Note that environment variables
35 are expanded, so ${USER}.conf becomes name.conf if USER=name. A special
36 environment variable KITTY_OS is available, to detect the operating
37 system. It is linux, macos or bsd. Also, you can use globinclude to
38 include files matching a shell glob pattern and envinclude to include
39 configuration from environment variables. For example:
40 include other.conf
42 # Include *.conf files from all subdirs of kitty.d inside the kitty config dir
43 globinclude kitty.d/**/*.conf
44 # Include the *contents* of all env vars starting with KITTY_CONF_
45 envinclude KITTY_CONF_*
46 NOTE:
48 Syntax highlighting for kitty.conf in vim is available via
49 vim-kitty.
50
52 kitty has very powerful font management. You can configure individual
53 font faces and even specify special fonts for particular characters.
54 font_family, bold_font, italic_font, bold_italic_font
56 font_family monospace
58 bold_font auto
59 italic_font auto
60 bold_italic_font auto
61 You can specify different fonts for the bold/italic/bold-italic vari‐
63 ants. To get a full list of supported fonts use the kitty +list-fonts
64 command. By default they are derived automatically, by the OSes font
65 system. When bold_font or bold_italic_font is set to auto on macOS, the
66 priority of bold fonts is semi-bold, bold, heavy. Setting them manually
67 is useful for font families that have many weight variants like Book,
68 Medium, Thick, etc. For example:
69 font_family Operator Mono Book
71 bold_font Operator Mono Medium
72 italic_font Operator Mono Book Italic
73 bold_italic_font Operator Mono Medium Italic
74 font_size
76 font_size 11.0
78 Font size (in pts)
80 force_ltr
82 force_ltr no
84 kitty does not support BIDI (bidirectional text), however, for RTL
86 scripts, words are automatically displayed in RTL. That is to say, in
87 an RTL script, the words "HELLO WORLD" display in kitty as "WORLD
88 HELLO", and if you try to select a substring of an RTL-shaped string,
89 you will get the character that would be there had the string been LTR.
90 For example, assuming the Hebrew word ירושלים, selecting the character
91 that on the screen appears to be ם actually writes into the selection
92 buffer the character י. kitty's default behavior is useful in conjunc‐
93 tion with a filter to reverse the word order, however, if you wish to
94 manipulate RTL glyphs, it can be very challenging to work with, so this
95 option is provided to turn it off. Furthermore, this option can be used
96 with the command line program GNU FriBidi to get BIDI support, because
97 it will force kitty to always treat the text as LTR, which FriBidi ex‐
98 pects for terminals.
99 symbol_map
101 Has no default values. Example values are shown below:
103 symbol_map U+E0A0-U+E0A3,U+E0C0-U+E0C7 PowerlineSymbols
105 Map the specified Unicode codepoints to a particular font. Useful if
107 you need special rendering for some symbols, such as for Powerline.
108 Avoids the need for patched fonts. Each Unicode code point is specified
109 in the form U+<code point in hexadecimal>. You can specify multiple
110 code points, separated by commas and ranges separated by hyphens. This
111 option can be specified multiple times. The syntax is:
112 symbol_map codepoints Font Family Name
114 narrow_symbols
116 Has no default values. Example values are shown below:
118 narrow_symbols U+E0A0-U+E0A3,U+E0C0-U+E0C7 1
120 Usually, for Private Use Unicode characters and some symbol/dingbat
122 characters, if the character is followed by one or more spaces, kitty
123 will use those extra cells to render the character larger, if the char‐
124 acter in the font has a wide aspect ratio. Using this option you can
125 force kitty to restrict the specified code points to render in the
126 specified number of cells (defaulting to one cell). This option can be
127 specified multiple times. The syntax is:
128 narrow_symbols codepoints [optionally the number of cells]
130 disable_ligatures
132 disable_ligatures never
134 Choose how you want to handle multi-character ligatures. The default is
136 to always render them. You can tell kitty to not render them when the
137 cursor is over them by using cursor to make editing easier, or have
138 kitty never render them at all by using always, if you don't like them.
139 The ligature strategy can be set per-window either using the kitty re‐
140 mote control facility or by defining shortcuts for it in kitty.conf,
141 for example:
142 map alt+1 disable_ligatures_in active always
144 map alt+2 disable_ligatures_in all never
145 map alt+3 disable_ligatures_in tab cursor
146 Note that this refers to programming ligatures, typically implemented
148 using the calt OpenType feature. For disabling general ligatures, use
149 the font_features option.
150 font_features
152 Has no default values. Example values are shown below:
154 font_features none
156 Choose exactly which OpenType features to enable or disable. This is
158 useful as some fonts might have features worthwhile in a terminal. For
159 example, Fira Code includes a discretionary feature, zero, which in
160 that font changes the appearance of the zero (0), to make it more eas‐
161 ily distinguishable from Ø. Fira Code also includes other discretionary
162 features known as Stylistic Sets which have the tags ss01 through ss20.
163 For the exact syntax to use for individual features, see the HarfBuzz
165 documentation.
166 Note that this code is indexed by PostScript name, and not the font
168 family. This allows you to define very precise feature settings; e.g.
169 you can disable a feature in the italic font but not in the regular
170 font.
171 On Linux, font features are first read from the FontConfig database and
173 then this option is applied, so they can be configured in a single,
174 central place.
175 To get the PostScript name for a font, use kitty +list-fonts --psnames:
177 $ kitty +list-fonts --psnames | grep Fira
179 Fira Code
180 Fira Code Bold (FiraCode-Bold)
181 Fira Code Light (FiraCode-Light)
182 Fira Code Medium (FiraCode-Medium)
183 Fira Code Regular (FiraCode-Regular)
184 Fira Code Retina (FiraCode-Retina)
185 The part in brackets is the PostScript name.
187 Enable alternate zero and oldstyle numerals:
189 font_features FiraCode-Retina +zero +onum
191 Enable only alternate zero in the bold font:
193 font_features FiraCode-Bold +zero
195 Disable the normal ligatures, but keep the calt feature which (in this
197 font) breaks up monotony:
198 font_features TT2020StyleB-Regular -liga +calt
200 In conjunction with force_ltr, you may want to disable Arabic shaping
202 entirely, and only look at their isolated forms if they show up in a
203 document. You can do this with e.g.:
204 font_features UnifontMedium +isol -medi -fina -init
206 modify_font
208 Modify font characteristics such as the position or thickness of the
210 underline and strikethrough. The modifications can have the suffix px
211 for pixels or % for percentage of original value. No suffix means use
212 pts. For example:
213 modify_font underline_position -2
215 modify_font underline_thickness 150%
216 modify_font strikethrough_position 2px
217 Additionally, you can modify the size of the cell in which each font
219 glyph is rendered and the baseline at which the glyph is placed in the
220 cell. For example:
221 modify_font cell_width 80%
223 modify_font cell_height -2px
224 modify_font baseline 3
225 Note that modifying the baseline will automatically adjust the under‐
227 line and strikethrough positions by the same amount. Increasing the
228 baseline raises glyphs inside the cell and decreasing it lowers them.
229 Decreasing the cell size might cause rendering artifacts, so use with
230 care.
231 box_drawing_scale
233 box_drawing_scale 0.001, 1, 1.5, 2
235 The sizes of the lines used for the box drawing Unicode characters.
237 These values are in pts. They will be scaled by the monitor DPI to ar‐
238 rive at a pixel value. There must be four values corresponding to
239 thin, normal, thick, and very thick lines.
240 undercurl_style
242 undercurl_style thin-sparse
244 The style with which undercurls are rendered. This option takes the
246 form (thin|thick)-(sparse|dense). Thin and thick control the thickness
247 of the undercurl. Sparse and dense control how often the curl oscil‐
248 lates. With sparse the curl will peak once per character, with dense
249 twice.
250 text_composition_strategy
252 text_composition_strategy platform
254 Control how kitty composites text glyphs onto the background color. The
256 default value of platform tries for text rendering as close to "native"
257 for the platform kitty is running on as possible.
258 A value of legacy uses the old (pre kitty 0.28) strategy for how glyphs
260 are composited. This will make dark text on light backgrounds look
261 thicker and light text on dark backgrounds thinner. It might also make
262 some text appear like the strokes are uneven.
263 You can fine tune the actual contrast curve used for glyph composition
265 by specifying up to two space-separated numbers for this setting.
266 The first number is the gamma adjustment, which controls the thickness
268 of dark text on light backgrounds. Increasing the value will make text
269 appear thicker. The default value for this is 1.0 on Linux and 1.7 on
270 macOS. Valid values are 0.01 and above. The result is scaled based on
271 the luminance difference between the background and the foreground.
272 Dark text on light backgrounds receives the full impact of the curve
273 while light text on dark backgrounds is affected very little.
274 The second number is an additional multiplicative contrast. It is per‐
276 centage ranging from 0 to 100. The default value is 0 on Linux and 30
277 on macOS.
278 If you wish to achieve similar looking thickness in light and dark
280 themes, a good way to experiment is start by setting the value to 1.0 0
281 and use a dark theme. Then adjust the second parameter until it looks
282 good. Then switch to a light theme and adjust the first parameter until
283 the perceived thickness matches the dark theme.
284 text_fg_override_threshold
286 text_fg_override_threshold 0
288 The minimum accepted difference in luminance between the foreground and
290 background color, below which kitty will override the foreground color.
291 It is percentage ranging from 0 to 100. If the difference in luminance
292 of the foreground and background is below this threshold, the fore‐
293 ground color will be set to white if the background is dark or black if
294 the background is light. The default value is 0, which means no over‐
295 riding is performed. Useful when working with applications that use
296 colors that do not contrast well with your preferred color scheme.
297 WARNING: Some programs use characters (such as block characters) for
299 graphics display and may expect to be able to set the foreground and
300 background to the same color (or similar colors). If you see unex‐
301 pected stripes, dots, lines, incorrect color, no color where you expect
302 color, or any kind of graphic display problem try setting
303 text_fg_override_threshold to 0 to see if this is the cause of the
304 problem.
305
307 cursor
308 cursor #cccccc
310 Default cursor color. If set to the special value none the cursor will
312 be rendered with a "reverse video" effect. It's color will be the color
313 of the text in the cell it is over and the text will be rendered with
314 the background color of the cell. Note that if the program running in
315 the terminal sets a cursor color, this takes precedence. Also, the cur‐
316 sor colors are modified if the cell background and foreground colors
317 have very low contrast.
318 cursor_text_color
320 cursor_text_color #111111
322 The color of text under the cursor. If you want it rendered with the
324 background color of the cell underneath instead, use the special key‐
325 word: background. Note that if cursor is set to none then this option
326 is ignored.
327 cursor_shape
329 cursor_shape block
331 The cursor shape can be one of block, beam, underline. Note that when
333 reloading the config this will be changed only if the cursor shape has
334 not been set by the program running in the terminal. This sets the de‐
335 fault cursor shape, applications running in the terminal can override
336 it. In particular, shell integration in kitty sets the cursor shape to
337 beam at shell prompts. You can avoid this by setting shell_integration
338 to no-cursor.
339 cursor_beam_thickness
341 cursor_beam_thickness 1.5
343 The thickness of the beam cursor (in pts).
345 cursor_underline_thickness
347 cursor_underline_thickness 2.0
349 The thickness of the underline cursor (in pts).
351 cursor_blink_interval
353 cursor_blink_interval -1
355 The interval to blink the cursor (in seconds). Set to zero to disable
357 blinking. Negative values mean use system default. Note that the mini‐
358 mum interval will be limited to repaint_delay.
359 cursor_stop_blinking_after
361 cursor_stop_blinking_after 15.0
363 Stop blinking cursor after the specified number of seconds of keyboard
365 inactivity. Set to zero to never stop blinking.
366
368 scrollback_lines
369 scrollback_lines 2000
371 Number of lines of history to keep in memory for scrolling back. Memory
373 is allocated on demand. Negative numbers are (effectively) infinite
374 scrollback. Note that using very large scrollback is not recommended
375 as it can slow down performance of the terminal and also use large
376 amounts of RAM. Instead, consider using scrollback_pager_history_size.
377 Note that on config reload if this is changed it will only affect newly
378 created windows, not existing ones.
379 scrollback_pager
381 scrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS +INPUT_LINE_NUMBER
383 Program with which to view scrollback in a new window. The scrollback
385 buffer is passed as STDIN to this program. If you change it, make sure
386 the program you use can handle ANSI escape sequences for colors and
387 text formatting. INPUT_LINE_NUMBER in the command line above will be
388 replaced by an integer representing which line should be at the top of
389 the screen. Similarly CURSOR_LINE and CURSOR_COLUMN will be replaced by
390 the current cursor position or set to 0 if there is no cursor, for ex‐
391 ample, when showing the last command output.
392 scrollback_pager_history_size
394 scrollback_pager_history_size 0
396 Separate scrollback history size (in MB), used only for browsing the
398 scrollback buffer with pager. This separate buffer is not available for
399 interactive scrolling but will be piped to the pager program when view‐
400 ing scrollback buffer in a separate window. The current implementation
401 stores the data in UTF-8, so approximately 10000 lines per megabyte at
402 100 chars per line, for pure ASCII, unformatted text. A value of zero
403 or less disables this feature. The maximum allowed size is 4GB. Note
404 that on config reload if this is changed it will only affect newly cre‐
405 ated windows, not existing ones.
406 scrollback_fill_enlarged_window
408 scrollback_fill_enlarged_window no
410 Fill new space with lines from the scrollback buffer after enlarging a
412 window.
413 wheel_scroll_multiplier
415 wheel_scroll_multiplier 5.0
417 Multiplier for the number of lines scrolled by the mouse wheel. Note
419 that this is only used for low precision scrolling devices, not for
420 high precision scrolling devices on platforms such as macOS and Way‐
421 land. Use negative numbers to change scroll direction. See also
422 wheel_scroll_min_lines.
423 wheel_scroll_min_lines
425 wheel_scroll_min_lines 1
427 The minimum number of lines scrolled by the mouse wheel. The scroll
429 multiplier only takes effect after it reaches this number. Note that
430 this is only used for low precision scrolling devices like wheel mice
431 that scroll by very small amounts when using the wheel. With a negative
432 number, the minimum number of lines will always be added.
433 touch_scroll_multiplier
435 touch_scroll_multiplier 1.0
437 Multiplier for the number of lines scrolled by a touchpad. Note that
439 this is only used for high precision scrolling devices on platforms
440 such as macOS and Wayland. Use negative numbers to change scroll direc‐
441 tion.
442
444 mouse_hide_wait
445 mouse_hide_wait 3.0
447 Hide mouse cursor after the specified number of seconds of the mouse
449 not being used. Set to zero to disable mouse cursor hiding. Set to a
450 negative value to hide the mouse cursor immediately when typing text.
451 Disabled by default on macOS as getting it to work robustly with the
452 ever-changing sea of bugs that is Cocoa is too much effort.
453 url_color, url_style
455 url_color #0087bd
457 url_style curly
458 The color and style for highlighting URLs on mouse-over. url_style can
460 be one of: none, straight, double, curly, dotted, dashed.
461 open_url_with
463 open_url_with default
465 The program to open clicked URLs. The special value default with first
467 look for any URL handlers defined via the Scripting the mouse click fa‐
468 cility and if non are found, it will use the Operating System's default
469 URL handler (open on macOS and xdg-open on Linux).
470 url_prefixes
472 url_prefixes file ftp ftps gemini git gopher http https irc ircs kitty mailto news sftp ssh
474 The set of URL prefixes to look for when detecting a URL under the
476 mouse cursor.
477 detect_urls
479 detect_urls yes
481 Detect URLs under the mouse. Detected URLs are highlighted with an un‐
483 derline and the mouse cursor becomes a hand over them. Even if this op‐
484 tion is disabled, URLs are still clickable. See also the
485 underline_hyperlinks option to control how hyperlinks (as opposed to
486 plain text URLs) are displayed.
487 url_excluded_characters
489 Additional characters to be disallowed from URLs, when detecting URLs
491 under the mouse cursor. By default, all characters that are legal in
492 URLs are allowed. Additionally, newlines are allowed (but stripped).
493 This is to accommodate programs such as mutt that add hard line breaks
494 even for continued lines. \n can be added to this option to disable
495 this behavior. Special characters can be specified using backslash es‐
496 capes, to specify a backslash use a double backslash.
497 show_hyperlink_targets
499 show_hyperlink_targets no
501 When the mouse hovers over a terminal hyperlink, show the actual URL
503 that will be activated when the hyperlink is clicked.
504 underline_hyperlinks
506 underline_hyperlinks hover
508 Control how hyperlinks are underlined. They can either be underlined on
510 mouse hover, always (i.e. permanently underlined) or never which means
511 that kitty will not apply any underline styling to hyperlinks. Uses
512 the url_style and url_color settings for the underline style. Note that
513 reloading the config and changing this value to/from always will only
514 affect text subsequently received by kitty.
515 copy_on_select
517 copy_on_select no
519 Copy to clipboard or a private buffer on select. With this set to clip‐
521 board, selecting text with the mouse will cause the text to be copied
522 to clipboard. Useful on platforms such as macOS that do not have the
523 concept of primary selection. You can instead specify a name such as a1
524 to copy to a private kitty buffer. Map a shortcut with the
525 paste_from_buffer action to paste from this private buffer. For exam‐
526 ple:
527 copy_on_select a1
529 map shift+cmd+v paste_from_buffer a1
530 Note that copying to the clipboard is a security risk, as all programs,
532 including websites open in your browser can read the contents of the
533 system clipboard.
534 paste_actions
536 paste_actions quote-urls-at-prompt,confirm
538 A comma separated list of actions to take when pasting text into the
540 terminal. The supported paste actions are:
541 quote-urls-at-prompt:
543 If the text being pasted is a URL and the cursor is at a shell
544 prompt, automatically quote the URL (needs shell_integration).
545 replace-dangerous-control-codes
547 Replace dangerous control codes from pasted text, without con‐
548 firmation.
549 replace-newline
551 Replace the newline character from pasted text, without confir‐
552 mation.
553 confirm:
555 Confirm the paste if the text to be pasted contains any terminal
556 control codes as this can be dangerous, leading to code execu‐
557 tion if the shell/program running in the terminal does not prop‐
558 erly handle these.
559 confirm-if-large
561 Confirm the paste if it is very large (larger than 16KB) as
562 pasting large amounts of text into shells can be very slow.
563 filter:
565 Run the filter_paste() function from the file paste-actions.py
566 in the kitty config directory on the pasted text. The text re‐
567 turned by the function will be actually pasted.
568 strip_trailing_spaces
570 strip_trailing_spaces never
572 Remove spaces at the end of lines when copying to clipboard. A value of
574 smart will do it when using normal selections, but not rectangle selec‐
575 tions. A value of always will always do it.
576 select_by_word_characters
578 select_by_word_characters @-./_~?&=%+#
580 Characters considered part of a word when double clicking. In addition
582 to these characters any character that is marked as an alphanumeric
583 character in the Unicode database will be matched.
584 select_by_word_characters_forward
586 Characters considered part of a word when extending the selection for‐
588 ward on double clicking. In addition to these characters any character
589 that is marked as an alphanumeric character in the Unicode database
590 will be matched.
591 If empty (default) select_by_word_characters will be used for both di‐
593 rections.
594 click_interval
596 click_interval -1.0
598 The interval between successive clicks to detect double/triple clicks
600 (in seconds). Negative numbers will use the system default instead, if
601 available, or fallback to 0.5.
602 focus_follows_mouse
604 focus_follows_mouse no
606 Set the active window to the window under the mouse when moving the
608 mouse around. On macOS, this will also cause the OS Window under the
609 mouse to be focused automatically when the mouse enters it.
610 pointer_shape_when_grabbed
612 pointer_shape_when_grabbed arrow
614 The shape of the mouse pointer when the program running in the terminal
616 grabs the mouse.
617 default_pointer_shape
619 default_pointer_shape beam
621 The default shape of the mouse pointer.
623 pointer_shape_when_dragging
625 pointer_shape_when_dragging beam
627 The default shape of the mouse pointer when dragging across text.
629 Mouse actions
631 Mouse buttons can be mapped to perform arbitrary actions. The syntax
632 is:
633 mouse_map button-name event-type modes action
635 Where button-name is one of left, middle, right, b1 ... b8 with added
637 keyboard modifiers. For example: ctrl+shift+left refers to holding the
638 Ctrl+Shift keys while clicking with the left mouse button. The value b1
639 ... b8 can be used to refer to up to eight buttons on a mouse.
640 event-type is one of press, release, doublepress, triplepress, click,
642 doubleclick. modes indicates whether the action is performed when the
643 mouse is grabbed by the program running in the terminal, or not. The
644 values are grabbed or ungrabbed or a comma separated combination of
645 them. grabbed refers to when the program running in the terminal has
646 requested mouse events. Note that the click and double click events
647 have a delay of click_interval to disambiguate from double and triple
648 presses.
649 You can run kitty with the kitty --debug-input command line option to
651 see mouse events. See the builtin actions below to get a sense of what
652 is possible.
653 If you want to unmap an action, map it to no_op. For example, to dis‐
655 able opening of URLs with a plain click:
656 mouse_map left click ungrabbed no_op
658 See all the mappable actions including mouse actions here.
660 NOTE:
662 Once a selection is started, releasing the button that started it
663 will automatically end it and no release event will be dispatched.
664 clear_all_mouse_actions
666 clear_all_mouse_actions no
668 Remove all mouse action definitions up to this point. Useful, for in‐
670 stance, to remove the default mouse actions.
671 Click the link under the mouse or move the cursor
673 mouse_map left click ungrabbed mouse_handle_click selection link prompt
675 First check for a selection and if one exists do nothing. Then check
677 for a link under the mouse cursor and if one exists, click it. Finally
678 check if the click happened at the current shell prompt and if so, move
679 the cursor to the click location. Note that this requires shell inte‐
680 gration to work.
681 Click the link under the mouse or move the cursor even when grabbed
683 mouse_map shift+left click grabbed,ungrabbed mouse_handle_click selection link prompt
685 Same as above, except that the action is performed even when the mouse
687 is grabbed by the program running in the terminal.
688 Click the link under the mouse cursor
690 mouse_map ctrl+shift+left release grabbed,ungrabbed mouse_handle_click link
692 Variant with Ctrl+Shift is present because the simple click based ver‐
694 sion has an unavoidable delay of click_interval, to disambiguate clicks
695 from double clicks.
696 Discard press event for link click
698 mouse_map ctrl+shift+left press grabbed discard_event
700 Prevent this press event from being sent to the program that has
702 grabbed the mouse, as the corresponding release event is used to open a
703 URL.
704 Paste from the primary selection
706 mouse_map middle release ungrabbed paste_from_selection
708 Start selecting text
710 mouse_map left press ungrabbed mouse_selection normal
712 Start selecting text in a rectangle
714 mouse_map ctrl+alt+left press ungrabbed mouse_selection rectangle
716 Select a word
718 mouse_map left doublepress ungrabbed mouse_selection word
720 Select a line
722 mouse_map left triplepress ungrabbed mouse_selection line
724 Select line from point
726 mouse_map ctrl+alt+left triplepress ungrabbed mouse_selection line_from_point
728 Select from the clicked point to the end of the line. If you would like
730 to select the word at the point and then extend to the rest of the
731 line, change line_from_point to word_and_line_from_point.
732 Extend the current selection
734 mouse_map right press ungrabbed mouse_selection extend
736 If you want only the end of the selection to be moved instead of the
738 nearest boundary, use move-end instead of extend.
739 Paste from the primary selection even when grabbed
741 mouse_map shift+middle release ungrabbed,grabbed paste_selection
743 mouse_map shift+middle press grabbed discard_event
744 Start selecting text even when grabbed
746 mouse_map shift+left press ungrabbed,grabbed mouse_selection normal
748 Start selecting text in a rectangle even when grabbed
750 mouse_map ctrl+shift+alt+left press ungrabbed,grabbed mouse_selection rectangle
752 Select a word even when grabbed
754 mouse_map shift+left doublepress ungrabbed,grabbed mouse_selection word
756 Select a line even when grabbed
758 mouse_map shift+left triplepress ungrabbed,grabbed mouse_selection line
760 Select line from point even when grabbed
762 mouse_map ctrl+shift+alt+left triplepress ungrabbed,grabbed mouse_selection line_from_point
764 Select from the clicked point to the end of the line even when grabbed.
766 If you would like to select the word at the point and then extend to
767 the rest of the line, change line_from_point to
768 word_and_line_from_point.
769 Extend the current selection even when grabbed
771 mouse_map shift+right press ungrabbed,grabbed mouse_selection extend
773 Show clicked command output in pager
775 mouse_map ctrl+shift+right press ungrabbed mouse_show_command_output
777 Requires shell integration to work.
779
781 repaint_delay
782 repaint_delay 10
784 Delay between screen updates (in milliseconds). Decreasing it, in‐
786 creases frames-per-second (FPS) at the cost of more CPU usage. The de‐
787 fault value yields ~100 FPS which is more than sufficient for most
788 uses. Note that to actually achieve 100 FPS, you have to either set
789 sync_to_monitor to no or use a monitor with a high refresh rate. Also,
790 to minimize latency when there is pending input to be processed, this
791 option is ignored.
792 input_delay
794 input_delay 3
796 Delay before input from the program running in the terminal is pro‐
798 cessed (in milliseconds). Note that decreasing it will increase respon‐
799 siveness, but also increase CPU usage and might cause flicker in full
800 screen programs that redraw the entire screen on each loop, because
801 kitty is so fast that partial screen updates will be drawn.
802 sync_to_monitor
804 sync_to_monitor yes
806 Sync screen updates to the refresh rate of the monitor. This prevents
808 screen tearing when scrolling. However, it limits the rendering speed
809 to the refresh rate of your monitor. With a very high speed mouse/high
810 keyboard repeat rate, you may notice some slight input latency. If so,
811 set this to no.
812
814 enable_audio_bell
815 enable_audio_bell yes
817 The audio bell. Useful to disable it in environments that require si‐
819 lence.
820 visual_bell_duration
822 visual_bell_duration 0.0
824 The visual bell duration (in seconds). Flash the screen when a bell oc‐
826 curs for the specified number of seconds. Set to zero to disable.
827 visual_bell_color
829 visual_bell_color none
831 The color used by visual bell. Set to none will fall back to selection
833 background color. If you feel that the visual bell is too bright, you
834 can set it to a darker color.
835 window_alert_on_bell
837 window_alert_on_bell yes
839 Request window attention on bell. Makes the dock icon bounce on macOS
841 or the taskbar flash on linux.
842 bell_on_tab
844 bell_on_tab "🔔 "
846 Some text or a Unicode symbol to show on the tab if a window in the tab
848 that does not have focus has a bell. If you want to use leading or
849 trailing spaces, surround the text with quotes. See tab_title_template
850 for how this is rendered.
851 For backwards compatibility, values of yes, y and true are converted to
853 the default bell symbol and no, n, false and none are converted to the
854 empty string.
855 command_on_bell
857 command_on_bell none
859 Program to run when a bell occurs. The environment variable
861 KITTY_CHILD_CMDLINE can be used to get the program running in the win‐
862 dow in which the bell occurred.
863 bell_path
865 bell_path none
867 Path to a sound file to play as the bell sound. If set to none, the
869 system default bell sound is used. Must be in a format supported by the
870 operating systems sound API, such as WAV or OGA on Linux (libcanberra)
871 or AIFF, MP3 or WAV on macOS (NSSound)
872 linux_bell_theme
874 linux_bell_theme __custom
876 The XDG Sound Theme kitty will use to play the bell sound. Defaults to
878 the custom theme name used by GNOME and Budgie, falling back to the de‐
879 fault freedesktop theme if it does not exist. This option may be re‐
880 moved if Linux ever provides desktop-agnostic support for setting sys‐
881 tem sound themes.
882
884 remember_window_size, initial_window_width, initial_window_height
885 remember_window_size yes
887 initial_window_width 640
888 initial_window_height 400
889 If enabled, the OS Window size will be remembered so that new instances
891 of kitty will have the same size as the previous instance. If dis‐
892 abled, the OS Window will initially have size configured by ini‐
893 tial_window_width/height, in pixels. You can use a suffix of "c" on the
894 width/height values to have them interpreted as number of cells instead
895 of pixels.
896 enabled_layouts
898 enabled_layouts *
900 The enabled window layouts. A comma separated list of layout names. The
902 special value all means all layouts. The first listed layout will be
903 used as the startup layout. Default configuration is all layouts in al‐
904 phabetical order. For a list of available layouts, see the Layouts.
905 window_resize_step_cells, window_resize_step_lines
907 window_resize_step_cells 2
909 window_resize_step_lines 2
910 The step size (in units of cell width/cell height) to use when resizing
912 kitty windows in a layout with the shortcut ctrl+shift+r. The cells
913 value is used for horizontal resizing, and the lines value is used for
914 vertical resizing.
915 window_border_width
917 window_border_width 0.5pt
919 The width of window borders. Can be either in pixels (px) or pts (pt).
921 Values in pts will be rounded to the nearest number of pixels based on
922 screen resolution. If not specified, the unit is assumed to be pts.
923 Note that borders are displayed only when more than one window is visi‐
924 ble. They are meant to separate multiple windows.
925 draw_minimal_borders
927 draw_minimal_borders yes
929 Draw only the minimum borders needed. This means that only the borders
931 that separate the window from a neighbor are drawn. Note that setting a
932 non-zero window_margin_width overrides this and causes all borders to
933 be drawn.
934 window_margin_width
936 window_margin_width 0
938 The window margin (in pts) (blank area outside the border). A single
940 value sets all four sides. Two values set the vertical and horizontal
941 sides. Three values set top, horizontal and bottom. Four values set
942 top, right, bottom and left.
943 single_window_margin_width
945 single_window_margin_width -1
947 The window margin to use when only a single window is visible (in pts).
949 Negative values will cause the value of window_margin_width to be used
950 instead. A single value sets all four sides. Two values set the verti‐
951 cal and horizontal sides. Three values set top, horizontal and bottom.
952 Four values set top, right, bottom and left.
953 window_padding_width
955 window_padding_width 0
957 The window padding (in pts) (blank area between the text and the window
959 border). A single value sets all four sides. Two values set the verti‐
960 cal and horizontal sides. Three values set top, horizontal and bottom.
961 Four values set top, right, bottom and left.
962 single_window_padding_width
964 single_window_padding_width -1
966 The window padding to use when only a single window is visible (in
968 pts). Negative values will cause the value of window_padding_width to
969 be used instead. A single value sets all four sides. Two values set the
970 vertical and horizontal sides. Three values set top, horizontal and
971 bottom. Four values set top, right, bottom and left.
972 placement_strategy
974 placement_strategy center
976 When the window size is not an exact multiple of the cell size, the
978 cell area of the terminal window will have some extra padding on the
979 sides. You can control how that padding is distributed with this op‐
980 tion. Using a value of center means the cell area will be placed cen‐
981 trally. A value of top-left means the padding will be only at the bot‐
982 tom and right edges.
983 active_border_color
985 active_border_color #00ff00
987 The color for the border of the active window. Set this to none to not
989 draw borders around the active window.
990 inactive_border_color
992 inactive_border_color #cccccc
994 The color for the border of inactive windows.
996 bell_border_color
998 bell_border_color #ff5a00
1000 The color for the border of inactive windows in which a bell has oc‐
1002 curred.
1003 inactive_text_alpha
1005 inactive_text_alpha 1.0
1007 Fade the text in inactive windows by the specified amount (a number be‐
1009 tween zero and one, with zero being fully faded).
1010 hide_window_decorations
1012 hide_window_decorations no
1014 Hide the window decorations (title-bar and window borders) with yes. On
1016 macOS, titlebar-only and titlebar-and-corners can be used to only hide
1017 the titlebar and the rounded corners. Whether this works and exactly
1018 what effect it has depends on the window manager/operating system. Note
1019 that the effects of changing this option when reloading config are un‐
1020 defined. When using titlebar-only, it is useful to also set
1021 window_margin_width and placement_strategy to prevent the rounded cor‐
1022 ners from clipping text. Or use titlebar-and-corners.
1023 window_logo_path
1025 window_logo_path none
1027 Path to a logo image. Must be in PNG format. Relative paths are inter‐
1029 preted relative to the kitty config directory. The logo is displayed in
1030 a corner of every kitty window. The position is controlled by
1031 window_logo_position. Individual windows can be configured to have
1032 different logos either using the launch action or the remote control
1033 facility.
1034 window_logo_position
1036 window_logo_position bottom-right
1038 Where to position the window logo in the window. The value can be one
1040 of: top-left, top, top-right, left, center, right, bottom-left, bottom,
1041 bottom-right.
1042 window_logo_alpha
1044 window_logo_alpha 0.5
1046 The amount the logo should be faded into the background. With zero be‐
1048 ing fully faded and one being fully opaque.
1049 resize_debounce_time
1051 resize_debounce_time 0.1 0.5
1053 The time to wait before redrawing the screen during a live resize of
1055 the OS window, when no new resize events have been received, i.e. when
1056 resizing is either paused or finished. On platforms such as macOS,
1057 where the operating system sends events corresponding to the start and
1058 end of a live resize, the second number is used for redraw-after-pause
1059 since kitty can distinguish between a pause and end of resizing. On
1060 such systems the first number is ignored and redraw is immediate after
1061 end of resize. On other systems the first number is used so that kitty
1062 is "ready" quickly after the end of resizing, while not also continu‐
1063 ously redrawing, to save energy.
1064 resize_in_steps
1066 resize_in_steps no
1068 Resize the OS window in steps as large as the cells, instead of with
1070 the usual pixel accuracy. Combined with initial_window_width and
1071 initial_window_height in number of cells, this option can be used to
1072 keep the margins as small as possible when resizing the OS window. Note
1073 that this does not currently work on Wayland.
1074 visual_window_select_characters
1076 visual_window_select_characters 1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ
1078 The list of characters for visual window selection. For example, for
1080 selecting a window to focus on with ctrl+shift+f7. The value should be
1081 a series of unique numbers or alphabets, case insensitive, from the set
1082 0-9A-Z`-=[];',./\. Specify your preference as a string of characters.
1083 confirm_os_window_close
1085 confirm_os_window_close -1
1087 Ask for confirmation when closing an OS window or a tab with at least
1089 this number of kitty windows in it by window manager (e.g. clicking the
1090 window close button or pressing the operating system shortcut to close
1091 windows) or by the close_tab action. A value of zero disables confirma‐
1092 tion. This confirmation also applies to requests to quit the entire ap‐
1093 plication (all OS windows, via the quit action). Negative values are
1094 converted to positive ones, however, with shell_integration enabled,
1095 using negative values means windows sitting at a shell prompt are not
1096 counted, only windows where some command is currently running. Note
1097 that if you want confirmation when closing individual windows, you can
1098 map the close_window_with_confirmation action.
1099
1101 tab_bar_edge
1102 tab_bar_edge bottom
1104 The edge to show the tab bar on, top or bottom.
1106 tab_bar_margin_width
1108 tab_bar_margin_width 0.0
1110 The margin to the left and right of the tab bar (in pts).
1112 tab_bar_margin_height
1114 tab_bar_margin_height 0.0 0.0
1116 The margin above and below the tab bar (in pts). The first number is
1118 the margin between the edge of the OS Window and the tab bar. The sec‐
1119 ond number is the margin between the tab bar and the contents of the
1120 current tab.
1121 tab_bar_style
1123 tab_bar_style fade
1125 The tab bar style, can be one of:
1127 fade Each tab's edges fade into the background color. (See also
1129 tab_fade)
1130 slant Tabs look like the tabs in a physical file.
1132 separator
1134 Tabs are separated by a configurable separator. (See also
1135 tab_separator)
1136 powerline
1138 Tabs are shown as a continuous line with "fancy" separators.
1139 (See also tab_powerline_style)
1140 custom A user-supplied Python function called draw_tab is loaded from
1142 the file tab_bar.py in the kitty config directory. For examples
1143 of how to write such a function, see the functions named
1144 draw_tab_with_* in kitty's source code: kitty/tab_bar.py. See
1145 also this discussion for examples from kitty users.
1146 hidden The tab bar is hidden. If you use this, you might want to create
1148 a mapping for the select_tab action which presents you with a
1149 list of tabs and allows for easy switching to a tab.
1150 tab_bar_align
1152 tab_bar_align left
1154 The horizontal alignment of the tab bar, can be one of: left, center,
1156 right.
1157 tab_bar_min_tabs
1159 tab_bar_min_tabs 2
1161 The minimum number of tabs that must exist before the tab bar is shown.
1163 tab_switch_strategy
1165 tab_switch_strategy previous
1167 The algorithm to use when switching to a tab when the current tab is
1169 closed. The default of previous will switch to the last used tab. A
1170 value of left will switch to the tab to the left of the closed tab. A
1171 value of right will switch to the tab to the right of the closed tab. A
1172 value of last will switch to the right-most tab.
1173 tab_fade
1175 tab_fade 0.25 0.5 0.75 1
1177 Control how each tab fades into the background when using fade for the
1179 tab_bar_style. Each number is an alpha (between zero and one) that con‐
1180 trols how much the corresponding cell fades into the background, with
1181 zero being no fade and one being full fade. You can change the number
1182 of cells used by adding/removing entries to this list.
1183 tab_separator
1185 tab_separator " ┇"
1187 The separator between tabs in the tab bar when using separator as the
1189 tab_bar_style.
1190 tab_powerline_style
1192 tab_powerline_style angled
1194 The powerline separator style between tabs in the tab bar when using
1196 powerline as the tab_bar_style, can be one of: angled, slanted, round.
1197 tab_activity_symbol
1199 tab_activity_symbol none
1201 Some text or a Unicode symbol to show on the tab if a window in the tab
1203 that does not have focus has some activity. If you want to use leading
1204 or trailing spaces, surround the text with quotes. See
1205 tab_title_template for how this is rendered.
1206 tab_title_max_length
1208 tab_title_max_length 0
1210 The maximum number of cells that can be used to render the text in a
1212 tab. A value of zero means that no limit is applied.
1213 tab_title_template
1215 tab_title_template "{fmt.fg.red}{bell_symbol}{activity_symbol}{fmt.fg.tab}{title}"
1217 A template to render the tab title. The default just renders the title
1219 with optional symbols for bell and activity. If you wish to include the
1220 tab-index as well, use something like: {index}:{title}. Useful if you
1221 have shortcuts mapped for goto_tab N. If you prefer to see the index as
1222 a superscript, use {sup.index}. All data available is:
1223 title The current tab title.
1225 index The tab index usable with goto_tab N shortcuts.
1227 layout_name
1229 The current layout name.
1230 num_windows
1232 The number of windows in the tab.
1233 num_window_groups
1235 The number of window groups (a window group is a window and all
1236 of its overlay windows) in the tab.
1237 tab.active_wd
1239 The working directory of the currently active window in the tab
1240 (expensive, requires syscall). Use active_oldest_wd to get the
1241 directory of the oldest foreground process rather than the new‐
1242 est.
1243 tab.active_exe
1245 The name of the executable running in the foreground of the cur‐
1246 rently active window in the tab (expensive, requires syscall).
1247 Use active_oldest_exe for the oldest foreground process.
1248 max_title_length
1250 The maximum title length available.
1251 Note that formatting is done by Python's string formatting machinery,
1253 so you can use, for instance, {layout_name[:2].upper()} to show only
1254 the first two letters of the layout name, upper-cased. If you want to
1255 style the text, you can use styling directives, for example:
1256 {fmt.fg.red}red{fmt.fg.tab}normal{fmt.bg._00FF00}greenbg{fmt.bg.tab}.
1257 Similarly, for bold and italic: {fmt.bold}bold{fmt.nobold}nor‐
1258 mal{fmt.italic}italic{fmt.noitalic}. Note that for backward compati‐
1259 bility, if {bell_symbol} or {activity_symbol} are not present in the
1260 template, they are prepended to it.
1261 active_tab_title_template
1263 active_tab_title_template none
1265 Template to use for active tabs. If not specified falls back to
1267 tab_title_template.
1268 active_tab_foreground, active_tab_background, active_tab_font_style,
1270 inactive_tab_foreground, inactive_tab_background, inac‐
1271 tive_tab_font_style
1272 active_tab_foreground #000
1274 active_tab_background #eee
1275 active_tab_font_style bold-italic
1276 inactive_tab_foreground #444
1277 inactive_tab_background #999
1278 inactive_tab_font_style normal
1279 Tab bar colors and styles.
1281 tab_bar_background
1283 tab_bar_background none
1285 Background color for the tab bar. Defaults to using the terminal back‐
1287 ground color.
1288 tab_bar_margin_color
1290 tab_bar_margin_color none
1292 Color for the tab bar margin area. Defaults to using the terminal back‐
1294 ground color for margins above and below the tab bar. For side margins
1295 the default color is chosen to match the background color of the neigh‐
1296 boring tab.
1297
1299 foreground, background
1300 foreground #dddddd
1302 background #000000
1303 The foreground and background colors.
1305 background_opacity
1307 background_opacity 1.0
1309 The opacity of the background. A number between zero and one, where one
1311 is opaque and zero is fully transparent. This will only work if sup‐
1312 ported by the OS (for instance, when using a compositor under X11).
1313 Note that it only sets the background color's opacity in cells that
1314 have the same background color as the default terminal background, so
1315 that things like the status bar in vim, powerline prompts, etc. still
1316 look good. But it means that if you use a color theme with a background
1317 color in your editor, it will not be rendered as transparent. Instead
1318 you should change the default background color in your kitty config and
1319 not use a background color in the editor color scheme. Or use the es‐
1320 cape codes to set the terminals default colors in a shell script to
1321 launch your editor. Be aware that using a value less than 1.0 is a
1322 (possibly significant) performance hit. When using a low value for this
1323 setting, it is desirable that you set the background color to a color
1324 the matches the general color of the desktop background, for best text
1325 rendering. If you want to dynamically change transparency of windows,
1326 set dynamic_background_opacity to yes (this is off by default as it has
1327 a performance cost). Changing this option when reloading the config
1328 will only work if dynamic_background_opacity was enabled in the origi‐
1329 nal config.
1330 background_blur
1332 background_blur 0
1334 Set to a positive value to enable background blur (blurring of the vi‐
1336 suals behind a transparent window) on platforms that support it. Only
1337 takes effect when background_opacity is less than one. On macOS, this
1338 will also control the blur radius (amount of blurring). Setting it to
1339 too high a value will cause severe performance issues and/or rendering
1340 artifacts. Usually, values up to 64 work well. Note that this might
1341 cause performance issues, depending on how the platform implements it,
1342 so use with care. Currently supported on macOS and KDE under X11.
1343 background_image
1345 background_image none
1347 Path to a background image. Must be in PNG format.
1349 background_image_layout
1351 background_image_layout tiled
1353 Whether to tile, scale or clamp the background image. The value can be
1355 one of tiled, mirror-tiled, scaled, clamped, centered or cscaled. The
1356 scaled and cscaled values scale the image to the window size, with
1357 cscaled preserving the image aspect ratio.
1358 background_image_linear
1360 background_image_linear no
1362 When background image is scaled, whether linear interpolation should be
1364 used.
1365 dynamic_background_opacity
1367 dynamic_background_opacity no
1369 Allow changing of the background_opacity dynamically, using either key‐
1371 board shortcuts (ctrl+shift+a>m and ctrl+shift+a>l) or the remote con‐
1372 trol facility. Changing this option by reloading the config is not sup‐
1373 ported.
1374 background_tint
1376 background_tint 0.0
1378 How much to tint the background image by the background color. This op‐
1380 tion makes it easier to read the text. Tinting is done using the cur‐
1381 rent background color for each window. This option applies only if
1382 background_opacity is set and transparent windows are supported or
1383 background_image is set.
1384 background_tint_gaps
1386 background_tint_gaps 1.0
1388 How much to tint the background image at the window gaps by the back‐
1390 ground color, after applying background_tint. Since this is multiplica‐
1391 tive with background_tint, it can be used to lighten the tint over the
1392 window gaps for a separated look.
1393 dim_opacity
1395 dim_opacity 0.4
1397 How much to dim text that has the DIM/FAINT attribute set. One means no
1399 dimming and zero means fully dimmed (i.e. invisible).
1400 selection_foreground, selection_background
1402 selection_foreground #000000
1404 selection_background #fffacd
1405 The foreground and background colors for text selected with the mouse.
1407 Setting both of these to none will cause a "reverse video" effect for
1408 selections, where the selection will be the cell text color and the
1409 text will become the cell background color. Setting only selec‐
1410 tion_foreground to none will cause the foreground color to be used un‐
1411 changed. Note that these colors can be overridden by the program run‐
1412 ning in the terminal.
1413 The color table
1415 The 256 terminal colors. There are 8 basic colors, each color has a
1416 dull and bright version, for the first 16 colors. You can set the re‐
1417 maining 240 colors as color16 to color255.
1418 color0, color8
1420 color0 #000000
1422 color8 #767676
1423 black
1425 color1, color9
1427 color1 #cc0403
1429 color9 #f2201f
1430 red
1432 color2, color10
1434 color2 #19cb00
1436 color10 #23fd00
1437 green
1439 color3, color11
1441 color3 #cecb00
1443 color11 #fffd00
1444 yellow
1446 color4, color12
1448 color4 #0d73cc
1450 color12 #1a8fff
1451 blue
1453 color5, color13
1455 color5 #cb1ed1
1457 color13 #fd28ff
1458 magenta
1460 color6, color14
1462 color6 #0dcdcd
1464 color14 #14ffff
1465 cyan
1467 color7, color15
1469 color7 #dddddd
1471 color15 #ffffff
1472 white
1474 mark1_foreground
1476 mark1_foreground black
1478 Color for marks of type 1
1480 mark1_background
1482 mark1_background #98d3cb
1484 Color for marks of type 1 (light steel blue)
1486 mark2_foreground
1488 mark2_foreground black
1490 Color for marks of type 2
1492 mark2_background
1494 mark2_background #f2dcd3
1496 Color for marks of type 1 (beige)
1498 mark3_foreground
1500 mark3_foreground black
1502 Color for marks of type 3
1504 mark3_background
1506 mark3_background #f274bc
1508 Color for marks of type 3 (violet)
1510
1512 shell
1513 shell .
1515 The shell program to execute. The default value of . means to use what‐
1517 ever shell is set as the default shell for the current user. Note that
1518 on macOS if you change this, you might need to add --login and --inter‐
1519 active to ensure that the shell starts in interactive mode and reads
1520 its startup rc files. Environment variables are expanded in this set‐
1521 ting.
1522 editor
1524 editor .
1526 The terminal based text editor (such as vim or nano) to use when edit‐
1528 ing the kitty config file or similar tasks.
1529 The default value of . means to use the environment variables VISUAL
1531 and EDITOR in that order. If these variables aren't set, kitty will run
1532 your shell ($SHELL -l -i -c env) to see if your shell startup rc files
1533 set VISUAL or EDITOR. If that doesn't work, kitty will cycle through
1534 various known editors (vim, emacs, etc.) and take the first one that
1535 exists on your system.
1536 close_on_child_death
1538 close_on_child_death no
1540 Close the window when the child process (shell) exits. With the default
1542 value no, the terminal will remain open when the child exits as long as
1543 there are still processes outputting to the terminal (for example dis‐
1544 owned or backgrounded processes). When enabled with yes, the window
1545 will close as soon as the child process exits. Note that setting it to
1546 yes means that any background processes still using the terminal can
1547 fail silently because their stdout/stderr/stdin no longer work.
1548 remote_control_password
1550 Allow other programs to control kitty using passwords. This option can
1552 be specified multiple times to add multiple passwords. If no passwords
1553 are present kitty will ask the user for permission if a program tries
1554 to use remote control with a password. A password can also optionally
1555 be associated with a set of allowed remote control actions. For exam‐
1556 ple:
1557 remote_control_password "my passphrase" get-colors set-colors focus-window focus-tab
1559 Only the specified actions will be allowed when using this password.
1561 Glob patterns can be used too, for example:
1562 remote_control_password "my passphrase" set-tab-* resize-*
1564 To get a list of available actions, run:
1566 kitten @ --help
1568 A set of actions to be allowed when no password is sent can be speci‐
1570 fied by using an empty password. For example:
1571 remote_control_password "" *-colors
1573 Finally, the path to a python module can be specified that provides a
1575 function is_cmd_allowed that is used to check every remote control com‐
1576 mand. For example:
1577 remote_control_password "my passphrase" my_rc_command_checker.py
1579 Relative paths are resolved from the kitty configuration directory.
1581 See Customizing authorization with your own program for details.
1582 allow_remote_control
1584 allow_remote_control no
1586 Allow other programs to control kitty. If you turn this on, other pro‐
1588 grams can control all aspects of kitty, including sending text to kitty
1589 windows, opening new windows, closing windows, reading the content of
1590 windows, etc. Note that this even works over SSH connections. The de‐
1591 fault setting of no prevents any form of remote control. The meaning of
1592 the various values are:
1593 password
1595 Remote control requests received over both the TTY device and
1596 the socket are confirmed based on passwords, see
1597 remote_control_password.
1598 socket-only
1600 Remote control requests received over a socket are accepted un‐
1601 conditionally. Requests received over the TTY are denied. See
1602 listen_on.
1603 socket Remote control requests received over a socket are accepted un‐
1605 conditionally. Requests received over the TTY are confirmed
1606 based on password.
1607 no Remote control is completely disabled.
1609 yes Remote control requests are always accepted.
1611 listen_on
1613 listen_on none
1615 Listen to the specified socket for remote control connections. Note
1617 that this will apply to all kitty instances. It can be overridden by
1618 the kitty --listen-on command line option. For UNIX sockets, such as
1619 unix:${TEMP}/mykitty or unix:@mykitty (on Linux). Environment variables
1620 are expanded and relative paths are resolved with respect to the tempo‐
1621 rary directory. If {kitty_pid} is present, then it is replaced by the
1622 PID of the kitty process, otherwise the PID of the kitty process is ap‐
1623 pended to the value, with a hyphen. For TCP sockets such as tcp:local‐
1624 host:0 a random port is always used even if a non-zero port number is
1625 specified. See the help for kitty --listen-on for more details. Note
1626 that this will be ignored unless allow_remote_control is set to either:
1627 yes, socket or socket-only. Changing this option by reloading the con‐
1628 fig is not supported.
1629 env
1631 Specify the environment variables to be set in all child processes. Us‐
1633 ing the name with an equal sign (e.g. env VAR=) will set it to the
1634 empty string. Specifying only the name (e.g. env VAR) will remove the
1635 variable from the child process' environment. Note that environment
1636 variables are expanded recursively, for example:
1637 env VAR1=a
1639 env VAR2=${HOME}/${VAR1}/b
1640 The value of VAR2 will be <path to home directory>/a/b.
1642 watcher
1644 Path to python file which will be loaded for Watching launched windows.
1646 Can be specified more than once to load multiple watchers. The watchers
1647 will be added to every kitty window. Relative paths are resolved rela‐
1648 tive to the kitty config directory. Note that reloading the config will
1649 only affect windows created after the reload.
1650 exe_search_path
1652 Control where kitty finds the programs to run. The default search order
1654 is: First search the system wide PATH, then ~/.local/bin and ~/bin. If
1655 still not found, the PATH defined in the login shell after sourcing all
1656 its startup files is tried. Finally, if present, the PATH specified by
1657 the env option is tried.
1658 This option allows you to prepend, append, or remove paths from this
1660 search order. It can be specified multiple times for multiple paths. A
1661 simple path will be prepended to the search order. A path that starts
1662 with the + sign will be append to the search order, after ~/bin above.
1663 A path that starts with the - sign will be removed from the entire
1664 search order. For example:
1665 exe_search_path /some/prepended/path
1667 exe_search_path +/some/appended/path
1668 exe_search_path -/some/excluded/path
1669 update_check_interval
1671 update_check_interval 24
1673 The interval to periodically check if an update to kitty is available
1675 (in hours). If an update is found, a system notification is displayed
1676 informing you of the available update. The default is to check every 24
1677 hours, set to zero to disable. Update checking is only done by the of‐
1678 ficial binary builds. Distro packages or source builds do not do update
1679 checking. Changing this option by reloading the config is not sup‐
1680 ported.
1681 startup_session
1683 startup_session none
1685 Path to a session file to use for all kitty instances. Can be overrid‐
1687 den by using the kitty --session =none command line option for individ‐
1688 ual instances. See Startup Sessions in the kitty documentation for de‐
1689 tails. Note that relative paths are interpreted with respect to the
1690 kitty config directory. Environment variables in the path are ex‐
1691 panded. Changing this option by reloading the config is not supported.
1692 clipboard_control
1694 clipboard_control write-clipboard write-primary read-clipboard-ask read-primary-ask
1696 Allow programs running in kitty to read and write from the clipboard.
1698 You can control exactly which actions are allowed. The possible actions
1699 are: write-clipboard, read-clipboard, write-primary, read-primary,
1700 read-clipboard-ask, read-primary-ask. The default is to allow writing
1701 to the clipboard and primary selection and to ask for permission when a
1702 program tries to read from the clipboard. Note that disabling the read
1703 confirmation is a security risk as it means that any program, even the
1704 ones running on a remote server via SSH can read your clipboard. See
1705 also clipboard_max_size.
1706 clipboard_max_size
1708 clipboard_max_size 512
1710 The maximum size (in MB) of data from programs running in kitty that
1712 will be stored for writing to the system clipboard. A value of zero
1713 means no size limit is applied. See also clipboard_control.
1714 file_transfer_confirmation_bypass
1716 The password that can be supplied to the file transfer kitten to skip
1718 the transfer confirmation prompt. This should only be used when initi‐
1719 ating transfers from trusted computers, over trusted networks or en‐
1720 crypted transports, as it allows any programs running on the remote ma‐
1721 chine to read/write to the local filesystem, without permission.
1722 allow_hyperlinks
1724 allow_hyperlinks yes
1726 Process hyperlink escape sequences (OSC 8). If disabled OSC 8 escape
1728 sequences are ignored. Otherwise they become clickable links, that you
1729 can click with the mouse or by using the hints kitten. The special
1730 value of ask means that kitty will ask before opening the link when
1731 clicked.
1732 shell_integration
1734 shell_integration enabled
1736 Enable shell integration on supported shells. This enables features
1738 such as jumping to previous prompts, browsing the output of the previ‐
1739 ous command in a pager, etc. on supported shells. Set to disabled to
1740 turn off shell integration, completely. It is also possible to disable
1741 individual features, set to a space separated list of these values:
1742 no-rc, no-cursor, no-title, no-cwd, no-prompt-mark, no-complete,
1743 no-sudo. See Shell integration for details.
1744 allow_cloning
1746 allow_cloning ask
1748 Control whether programs running in the terminal can request new win‐
1750 dows to be created. The canonical example is clone-in-kitty. By de‐
1751 fault, kitty will ask for permission for each clone request. Allowing
1752 cloning unconditionally gives programs running in the terminal (includ‐
1753 ing over SSH) permission to execute arbitrary code, as the user who is
1754 running the terminal, on the computer that the terminal is running on.
1755 clone_source_strategies
1757 clone_source_strategies venv,conda,env_var,path
1759 Control what shell code is sourced when running clone-in-kitty in the
1761 newly cloned window. The supported strategies are:
1762 venv Source the file $VIRTUAL_ENV/bin/activate. This is used by the
1764 Python stdlib venv module and allows cloning venvs automati‐
1765 cally.
1766 conda Run conda activate $CONDA_DEFAULT_ENV. This supports the virtual
1768 environments created by conda.
1769 env_var
1771 Execute the contents of the environment variable
1772 KITTY_CLONE_SOURCE_CODE with eval.
1773 path Source the file pointed to by the environment variable
1775 KITTY_CLONE_SOURCE_PATH.
1776 This option must be a comma separated list of the above values. Only
1778 the first valid match, in the order specified, is sourced.
1779 term
1781 term xterm-kitty
1783 The value of the TERM environment variable to set. Changing this can
1785 break many terminal programs, only change it if you know what you are
1786 doing, not because you read some advice on "Stack Overflow" to change
1787 it. The TERM variable is used by various programs to get information
1788 about the capabilities and behavior of the terminal. If you change it,
1789 depending on what programs you run, and how different the terminal you
1790 are changing it to is, various things from key-presses, to colors, to
1791 various advanced features may not work. Changing this option by reload‐
1792 ing the config will only affect newly created windows.
1793 forward_stdio
1795 forward_stdio no
1797 Forward STDOUT and STDERR of the kitty process to child processes as
1799 file descriptors 3 and 4. This is useful for debugging as it allows
1800 child processes to print to kitty's STDOUT directly. For example, echo
1801 hello world >&3 in a shell will print to the parent kitty's STDOUT.
1802 When enabled, this also sets the KITTY_STDIO_FORWARDED=3 environment
1803 variable so child processes know about the forwarding.
1804 menu_map
1806 Specify entries for various menus in kitty. Currently only the global
1808 menubar on macOS is supported. For example:
1809 menu_map global "Actions::Launch something special" launch --hold --type=os-window sh -c "echo hello world"
1811 This will create a menu entry named "Launch something special" in an
1813 "Actions" menu in the macOS global menubar. Sub-menus can be created
1814 by adding more levels separated by ::.
1815
1817 wayland_titlebar_color
1818 wayland_titlebar_color system
1820 The color of the kitty window's titlebar on Wayland systems with client
1822 side window decorations such as GNOME. A value of system means to use
1823 the default system color, a value of background means to use the back‐
1824 ground color of the currently active window and finally you can use an
1825 arbitrary color, such as #12af59 or red.
1826 macos_titlebar_color
1828 macos_titlebar_color system
1830 The color of the kitty window's titlebar on macOS. A value of system
1832 means to use the default system color, light or dark can also be used
1833 to set it explicitly. A value of background means to use the background
1834 color of the currently active window and finally you can use an arbi‐
1835 trary color, such as #12af59 or red. WARNING: This option works by us‐
1836 ing a hack when arbitrary color (or background) is configured, as there
1837 is no proper Cocoa API for it. It sets the background color of the en‐
1838 tire window and makes the titlebar transparent. As such it is incompat‐
1839 ible with background_opacity. If you want to use both, you are probably
1840 better off just hiding the titlebar with hide_window_decorations.
1841 macos_option_as_alt
1843 macos_option_as_alt no
1845 Use the Option key as an Alt key on macOS. With this set to no, kitty
1847 will use the macOS native Option+Key to enter Unicode character behav‐
1848 ior. This will break any Alt+Key keyboard shortcuts in your terminal
1849 programs, but you can use the macOS Unicode input technique. You can
1850 use the values: left, right or both to use only the left, right or both
1851 Option keys as Alt, instead. Note that kitty itself always treats Op‐
1852 tion the same as Alt. This means you cannot use this option to config‐
1853 ure different kitty shortcuts for Option+Key vs. Alt+Key. Also, any
1854 kitty shortcuts using Option/Alt+Key will take priority, so that any
1855 such key presses will not be passed to terminal programs running inside
1856 kitty. Changing this option by reloading the config is not supported.
1857 macos_hide_from_tasks
1859 macos_hide_from_tasks no
1861 Hide the kitty window from running tasks on macOS (⌘+Tab and the Dock).
1863 Changing this option by reloading the config is not supported.
1864 macos_quit_when_last_window_closed
1866 macos_quit_when_last_window_closed no
1868 Have kitty quit when all the top-level windows are closed on macOS. By
1870 default, kitty will stay running, even with no open windows, as is the
1871 expected behavior on macOS.
1872 macos_window_resizable
1874 macos_window_resizable yes
1876 Disable this if you want kitty top-level OS windows to not be resizable
1878 on macOS.
1879 macos_thicken_font
1881 macos_thicken_font 0
1883 Draw an extra border around the font with the given width, to increase
1885 legibility at small font sizes on macOS. For example, a value of 0.75
1886 will result in rendering that looks similar to sub-pixel antialiasing
1887 at common font sizes. Note that in modern kitty, this option is obso‐
1888 lete (although still supported). Consider using
1889 text_composition_strategy instead.
1890 macos_traditional_fullscreen
1892 macos_traditional_fullscreen no
1894 Use the macOS traditional full-screen transition, that is faster, but
1896 less pretty.
1897 macos_show_window_title_in
1899 macos_show_window_title_in all
1901 Control where the window title is displayed on macOS. A value of window
1903 will show the title of the currently active window at the top of the
1904 macOS window. A value of menubar will show the title of the currently
1905 active window in the macOS global menu bar, making use of otherwise
1906 wasted space. A value of all will show the title in both places, and
1907 none hides the title. See macos_menubar_title_max_length for how to
1908 control the length of the title in the menu bar.
1909 macos_menubar_title_max_length
1911 macos_menubar_title_max_length 0
1913 The maximum number of characters from the window title to show in the
1915 macOS global menu bar. Values less than one means that there is no max‐
1916 imum limit.
1917 macos_custom_beam_cursor
1919 macos_custom_beam_cursor no
1921 Use a custom mouse cursor for macOS that is easier to see on both light
1923 and dark backgrounds. Nowadays, the default macOS cursor already comes
1924 with a white border. WARNING: this might make your mouse cursor invisi‐
1925 ble on dual GPU machines. Changing this option by reloading the config
1926 is not supported.
1927 macos_colorspace
1929 macos_colorspace srgb
1931 The colorspace in which to interpret terminal colors. The default of
1933 srgb will cause colors to match those seen in web browsers. The value
1934 of default will use whatever the native colorspace of the display is.
1935 The value of displayp3 will use Apple's special snowflake display P3
1936 color space, which will result in over saturated (brighter) colors with
1937 some color shift. Reloading configuration will change this value only
1938 for newly created OS windows.
1939 linux_display_server
1941 linux_display_server auto
1943 Choose between Wayland and X11 backends. By default, an appropriate
1945 backend based on the system state is chosen automatically. Set it to
1946 x11 or wayland to force the choice. Changing this option by reloading
1947 the config is not supported.
1948
1950 Keys are identified simply by their lowercase Unicode characters. For
1951 example: a for the A key, [ for the left square bracket key, etc. For
1952 functional keys, such as Enter or Escape, the names are present at
1953 Functional key definitions. For modifier keys, the names are ctrl (con‐
1954 trol, ⌃), shift (⇧), alt (opt, option, ⌥), super (cmd, command, ⌘).
1955 See also: GLFW mods
1956 On Linux you can also use XKB key names to bind keys that are not sup‐
1958 ported by GLFW. See XKB keys for a list of key names. The name to use
1959 is the part after the XKB_KEY_ prefix. Note that you can only use an
1960 XKB key name for keys that are not known as GLFW keys.
1961 Finally, you can use raw system key codes to map keys, again only for
1963 keys that are not known as GLFW keys. To see the system key code for a
1964 key, start kitty with the kitty --debug-input option, kitty will output
1965 some debug text for every key event. In that text look for native_code,
1966 the value of that becomes the key name in the shortcut. For example:
1967 on_key_input: glfw key: 0x61 native_code: 0x61 action: PRESS mods: none text: 'a'
1969 Here, the key name for the A key is 0x61 and you can use it with:
1971 map ctrl+0x61 something
1973 to map Ctrl+A to something.
1975 You can use the special action no_op to unmap a keyboard shortcut that
1977 is assigned in the default configuration:
1978 map kitty_mod+space no_op
1980 If you would like kitty to completely ignore a key event, not even
1982 sending it to the program running in the terminal, map it to
1983 discard_event:
1984 map kitty_mod+f1 discard_event
1986 You can combine multiple actions to be triggered by a single shortcut
1988 with combine action, using the syntax below:
1989 map key combine <separator> action1 <separator> action2 <separator> action3 ...
1991 For example:
1993 map kitty_mod+e combine : new_window : next_layout
1995 This will create a new window and switch to the next available layout.
1997 You can use multi-key shortcuts with the syntax shown below:
1999 map key1>key2>key3 action
2001 For example:
2003 map ctrl+f>2 set_font_size 20
2005 The full list of actions that can be mapped to key presses is available
2007 here.
2008 kitty_mod
2010 kitty_mod ctrl+shift
2012 Special modifier key alias for default shortcuts. You can change the
2014 value of this option to alter all default shortcuts that use kitty_mod.
2015 clear_all_shortcuts
2017 clear_all_shortcuts no
2019 Remove all shortcut definitions up to this point. Useful, for instance,
2021 to remove the default shortcuts.
2022 action_alias
2024 Has no default values. Example values are shown below:
2026 action_alias launch_tab launch --type=tab --cwd=current
2028 Define action aliases to avoid repeating the same options in multiple
2030 mappings. Aliases can be defined for any action and will be expanded
2031 recursively. For example, the above alias allows you to create mappings
2032 to launch a new tab in the current working directory without duplica‐
2033 tion:
2034 map f1 launch_tab vim
2036 map f2 launch_tab emacs
2037 Similarly, to alias kitten invocation:
2039 action_alias hints kitten hints --hints-offset=0
2041 kitten_alias
2043 Has no default values. Example values are shown below:
2045 kitten_alias hints hints --hints-offset=0
2047 Like action_alias above, but specifically for kittens. Generally, pre‐
2049 fer to use action_alias. This option is a legacy version, present for
2050 backwards compatibility. It causes all invocations of the aliased kit‐
2051 ten to be substituted. So the example above will cause all invocations
2052 of the hints kitten to have the --hints-offset=0 option applied.
2053 Clipboard
2055 Copy to clipboard
2056 map ctrl+shift+c copy_to_clipboard
2058 map cmd+c copy_to_clipboard 🍎
2059 There is also a copy_or_interrupt action that can be optionally mapped
2061 to Ctrl+C. It will copy only if there is a selection and send an inter‐
2062 rupt otherwise. Similarly, copy_and_clear_or_interrupt will copy and
2063 clear the selection or send an interrupt if there is no selection.
2064 Paste from clipboard
2066 map ctrl+shift+v paste_from_clipboard
2068 map cmd+v paste_from_clipboard 🍎
2069 Paste from selection
2071 map ctrl+shift+s paste_from_selection
2073 map shift+insert paste_from_selection
2074 Pass selection to program
2076 map ctrl+shift+o pass_selection_to_program
2078 You can also pass the contents of the current selection to any program
2080 with pass_selection_to_program. By default, the system's open program
2081 is used, but you can specify your own, the selection will be passed as
2082 a command line argument to the program. For example:
2083 map kitty_mod+o pass_selection_to_program firefox
2085 You can pass the current selection to a terminal program running in a
2087 new kitty window, by using the @selection placeholder:
2088 map kitty_mod+y new_window less @selection
2090 Scrolling
2092 Scroll line up
2093 map ctrl+shift+up scroll_line_up
2095 map ctrl+shift+k scroll_line_up
2096 map opt+cmd+page_up scroll_line_up 🍎
2097 map cmd+up scroll_line_up 🍎
2098 Scroll line down
2100 map ctrl+shift+down scroll_line_down
2102 map ctrl+shift+j scroll_line_down
2103 map opt+cmd+page_down scroll_line_down 🍎
2104 map cmd+down scroll_line_down 🍎
2105 Scroll page up
2107 map ctrl+shift+page_up scroll_page_up
2109 map cmd+page_up scroll_page_up 🍎
2110 Scroll page down
2112 map ctrl+shift+page_down scroll_page_down
2114 map cmd+page_down scroll_page_down 🍎
2115 Scroll to top
2117 map ctrl+shift+home scroll_home
2119 map cmd+home scroll_home 🍎
2120 Scroll to bottom
2122 map ctrl+shift+end scroll_end
2124 map cmd+end scroll_end 🍎
2125 Scroll to previous shell prompt
2127 map ctrl+shift+z scroll_to_prompt -1
2129 Use a parameter of 0 for scroll_to_prompt to scroll to the last jumped
2131 to or the last clicked position. Requires shell integration to work.
2132 Scroll to next shell prompt
2134 map ctrl+shift+x scroll_to_prompt 1
2136 Browse scrollback buffer in pager
2138 map ctrl+shift+h show_scrollback
2140 You can pipe the contents of the current screen and history buffer as
2142 STDIN to an arbitrary program using launch --stdin-source. For exam‐
2143 ple, the following opens the scrollback buffer in less in an overlay
2144 window:
2145 map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting --type=overlay less +G -R
2147 For more details on piping screen and buffer contents to external pro‐
2149 grams, see The launch command.
2150 Browse output of the last shell command in pager
2152 map ctrl+shift+g show_last_command_output
2154 You can also define additional shortcuts to get the command output.
2156 For example, to get the first command output on screen:
2157 map f1 show_first_command_output_on_screen
2159 To get the command output that was last accessed by a keyboard action
2161 or mouse action:
2162 map f1 show_last_visited_command_output
2164 You can pipe the output of the last command run in the shell using the
2166 launch action. For example, the following opens the output in less in
2167 an overlay window:
2168 map f1 launch --stdin-source=@last_cmd_output --stdin-add-formatting --type=overlay less +G -R
2170 To get the output of the first command on the screen, use
2172 @first_cmd_output_on_screen. To get the output of the last jumped to
2173 command, use @last_visited_cmd_output.
2174 Requires shell integration to work.
2176 Window management
2178 New window
2179 map ctrl+shift+enter new_window
2181 map cmd+enter new_window 🍎
2182 You can open a new kitty window running an arbitrary program, for exam‐
2184 ple:
2185 map kitty_mod+y launch mutt
2187 You can open a new window with the current working directory set to the
2189 working directory of the current window using:
2190 map ctrl+alt+enter launch --cwd=current
2192 You can open a new window that is allowed to control kitty via the
2194 kitty remote control facility with launch --allow-remote-control. Any
2195 programs running in that window will be allowed to control kitty. For
2196 example:
2197 map ctrl+enter launch --allow-remote-control some_program
2199 You can open a new window next to the currently active window or as the
2201 first window, with:
2202 map ctrl+n launch --location=neighbor
2204 map ctrl+f launch --location=first
2205 For more details, see The launch command.
2207 New OS window
2209 map ctrl+shift+n new_os_window
2211 map cmd+n new_os_window 🍎
2212 Works like new_window above, except that it opens a top-level OS win‐
2214 dow. In particular you can use new_os_window_with_cwd to open a window
2215 with the current working directory.
2216 Close window
2218 map ctrl+shift+w close_window
2220 map shift+cmd+d close_window 🍎
2221 Next window
2223 map ctrl+shift+] next_window
2225 Previous window
2227 map ctrl+shift+[ previous_window
2229 Move window forward
2231 map ctrl+shift+f move_window_forward
2233 Move window backward
2235 map ctrl+shift+b move_window_backward
2237 Move window to top
2239 map ctrl+shift+` move_window_to_top
2241 Start resizing window
2243 map ctrl+shift+r start_resizing_window
2245 map cmd+r start_resizing_window 🍎
2246 First window
2248 map ctrl+shift+1 first_window
2250 map cmd+1 first_window 🍎
2251 Second window
2253 map ctrl+shift+2 second_window
2255 map cmd+2 second_window 🍎
2256 Third window
2258 map ctrl+shift+3 third_window
2260 map cmd+3 third_window 🍎
2261 Fourth window
2263 map ctrl+shift+4 fourth_window
2265 map cmd+4 fourth_window 🍎
2266 Fifth window
2268 map ctrl+shift+5 fifth_window
2270 map cmd+5 fifth_window 🍎
2271 Sixth window
2273 map ctrl+shift+6 sixth_window
2275 map cmd+6 sixth_window 🍎
2276 Seventh window
2278 map ctrl+shift+7 seventh_window
2280 map cmd+7 seventh_window 🍎
2281 Eighth window
2283 map ctrl+shift+8 eighth_window
2285 map cmd+8 eighth_window 🍎
2286 Ninth window
2288 map ctrl+shift+9 ninth_window
2290 map cmd+9 ninth_window 🍎
2291 Tenth window
2293 map ctrl+shift+0 tenth_window
2295 Visually select and focus window
2297 map ctrl+shift+f7 focus_visible_window
2299 Display overlay numbers and alphabets on the window, and switch the fo‐
2301 cus to the window when you press the key. When there are only two win‐
2302 dows, the focus will be switched directly without displaying the over‐
2303 lay. You can change the overlay characters and their order with option
2304 visual_window_select_characters.
2305 Visually swap window with another
2307 map ctrl+shift+f8 swap_with_window
2309 Works like focus_visible_window above, but swaps the window.
2311 Tab management
2313 Next tab
2314 map ctrl+shift+right next_tab
2316 map shift+cmd+] next_tab 🍎
2317 map ctrl+tab next_tab
2318 Previous tab
2320 map ctrl+shift+left previous_tab
2322 map shift+cmd+[ previous_tab 🍎
2323 map ctrl+shift+tab previous_tab
2324 New tab
2326 map ctrl+shift+t new_tab
2328 map cmd+t new_tab 🍎
2329 Close tab
2331 map ctrl+shift+q close_tab
2333 map cmd+w close_tab 🍎
2334 Close OS window
2336 map shift+cmd+w close_os_window 🍎
2338 Move tab forward
2340 map ctrl+shift+. move_tab_forward
2342 Move tab backward
2344 map ctrl+shift+, move_tab_backward
2346 Set tab title
2348 map ctrl+shift+alt+t set_tab_title
2350 map shift+cmd+i set_tab_title 🍎
2351 You can also create shortcuts to go to specific tabs, with 1 being the
2353 first tab, 2 the second tab and -1 being the previously active tab, and
2354 any number larger than the last tab being the last tab:
2355 map ctrl+alt+1 goto_tab 1
2357 map ctrl+alt+2 goto_tab 2
2358 Just as with new_window above, you can also pass the name of arbitrary
2360 commands to run when using new_tab and new_tab_with_cwd. Finally, if
2361 you want the new tab to open next to the current tab rather than at the
2362 end of the tabs list, use:
2363 map ctrl+t new_tab !neighbor [optional cmd to run]
2365 Layout management
2367 Next layout
2368 map ctrl+shift+l next_layout
2370 You can also create shortcuts to switch to specific layouts:
2372 map ctrl+alt+t goto_layout tall
2374 map ctrl+alt+s goto_layout stack
2375 Similarly, to switch back to the previous layout:
2377 map ctrl+alt+p last_used_layout
2379 There is also a toggle_layout action that switches to the named layout
2381 or back to the previous layout if in the named layout. Useful to tempo‐
2382 rarily "zoom" the active window by switching to the stack layout:
2383 map ctrl+alt+z toggle_layout stack
2385 Font sizes
2387 You can change the font size for all top-level kitty OS windows at a
2388 time or only the current one.
2389 Increase font size
2391 map ctrl+shift+equal change_font_size all +2.0
2393 map ctrl+shift+plus change_font_size all +2.0
2394 map ctrl+shift+kp_add change_font_size all +2.0
2395 map cmd+plus change_font_size all +2.0 🍎
2396 map cmd+equal change_font_size all +2.0 🍎
2397 map shift+cmd+equal change_font_size all +2.0 🍎
2398 Decrease font size
2400 map ctrl+shift+minus change_font_size all -2.0
2402 map ctrl+shift+kp_subtract change_font_size all -2.0
2403 map cmd+minus change_font_size all -2.0 🍎
2404 map shift+cmd+minus change_font_size all -2.0 🍎
2405 Reset font size
2407 map ctrl+shift+backspace change_font_size all 0
2409 map cmd+0 change_font_size all 0 🍎
2410 To setup shortcuts for specific font sizes:
2412 map kitty_mod+f6 change_font_size all 10.0
2414 To setup shortcuts to change only the current OS window's font size:
2416 map kitty_mod+f6 change_font_size current 10.0
2418 Select and act on visible text
2420 Use the hints kitten to select text and either pass it to an external
2421 program or insert it into the terminal or copy it to the clipboard.
2422 Open URL
2424 map ctrl+shift+e open_url_with_hints
2426 Open a currently visible URL using the keyboard. The program used to
2428 open the URL is specified in open_url_with.
2429 Insert selected path
2431 map ctrl+shift+p>f kitten hints --type path --program -
2433 Select a path/filename and insert it into the terminal. Useful, for in‐
2435 stance to run git commands on a filename output from a previous git
2436 command.
2437 Open selected path
2439 map ctrl+shift+p>shift+f kitten hints --type path
2441 Select a path/filename and open it with the default open program.
2443 Insert selected line
2445 map ctrl+shift+p>l kitten hints --type line --program -
2447 Select a line of text and insert it into the terminal. Useful for the
2449 output of things like: ls -1.
2450 Insert selected word
2452 map ctrl+shift+p>w kitten hints --type word --program -
2454 Select words and insert into terminal.
2456 Insert selected hash
2458 map ctrl+shift+p>h kitten hints --type hash --program -
2460 Select something that looks like a hash and insert it into the termi‐
2462 nal. Useful with git, which uses SHA1 hashes to identify commits.
2463 Open the selected file at the selected line
2465 map ctrl+shift+p>n kitten hints --type linenum
2467 Select something that looks like filename:linenum and open it in vim at
2469 the specified line number.
2470 Open the selected hyperlink
2472 map ctrl+shift+p>y kitten hints --type hyperlink
2474 Select a hyperlink (i.e. a URL that has been marked as such by the ter‐
2476 minal program, for example, by ls --hyperlink=auto).
2477 The hints kitten has many more modes of operation that you can map to
2479 different shortcuts. For a full description see hints kitten.
2480 Miscellaneous
2482 Show documentation
2483 map ctrl+shift+f1 show_kitty_doc overview
2485 Toggle fullscreen
2487 map ctrl+shift+f11 toggle_fullscreen
2489 map ctrl+cmd+f toggle_fullscreen 🍎
2490 Toggle maximized
2492 map ctrl+shift+f10 toggle_maximized
2494 Toggle macOS secure keyboard entry
2496 map opt+cmd+s toggle_macos_secure_keyboard_entry 🍎
2498 Unicode input
2500 map ctrl+shift+u kitten unicode_input
2502 map ctrl+cmd+space kitten unicode_input 🍎
2503 Edit config file
2505 map ctrl+shift+f2 edit_config_file
2507 map cmd+, edit_config_file 🍎
2508 Open the kitty command shell
2510 map ctrl+shift+escape kitty_shell window
2512 Open the kitty shell in a new window / tab / overlay / os_window to
2514 control kitty using commands.
2515 Increase background opacity
2517 map ctrl+shift+a>m set_background_opacity +0.1
2519 Decrease background opacity
2521 map ctrl+shift+a>l set_background_opacity -0.1
2523 Make background fully opaque
2525 map ctrl+shift+a>1 set_background_opacity 1
2527 Reset background opacity
2529 map ctrl+shift+a>d set_background_opacity default
2531 Reset the terminal
2533 map ctrl+shift+delete clear_terminal reset active
2535 map opt+cmd+r clear_terminal reset active 🍎
2536 You can create shortcuts to clear/reset the terminal. For example:
2538 # Reset the terminal
2540 map f1 clear_terminal reset active
2541 # Clear the terminal screen by erasing all contents
2542 map f1 clear_terminal clear active
2543 # Clear the terminal scrollback by erasing it
2544 map f1 clear_terminal scrollback active
2545 # Scroll the contents of the screen into the scrollback
2546 map f1 clear_terminal scroll active
2547 # Clear everything up to the line with the cursor
2548 map f1 clear_terminal to_cursor active
2549 If you want to operate on all kitty windows instead of just the current
2551 one, use all instead of active.
2552 Some useful functions that can be defined in the shell rc files to per‐
2554 form various kinds of clearing of the current window:
2555 clear-only-screen() {
2557 printf "\e[H\e[2J"
2558 }
2559 clear-screen-and-scrollback() {
2561 printf "\e[H\e[3J"
2562 }
2563 clear-screen-saving-contents-in-scrollback() {
2565 printf "\e[H\e[22J"
2566 }
2567 For instance, using these escape codes, it is possible to remap Ctrl+L
2569 to both scroll the current screen contents into the scrollback buffer
2570 and clear the screen, instead of just clearing the screen. For ZSH, in
2571 ~/.zshrc, add:
2572 ctrl_l() {
2574 builtin print -rn -- $'\r\e[0J\e[H\e[22J' >"$TTY"
2575 builtin zle .reset-prompt
2576 builtin zle -R
2577 }
2578 zle -N ctrl_l
2579 bindkey '^l' ctrl_l
2580 Clear up to cursor line
2582 map cmd+k clear_terminal to_cursor active 🍎
2584 Reload kitty.conf
2586 map ctrl+shift+f5 load_config_file
2588 map ctrl+cmd+, load_config_file 🍎
2589 Reload kitty.conf, applying any changes since the last time it was
2591 loaded. Note that a handful of options cannot be dynamically changed
2592 and require a full restart of kitty. Particularly, when changing short‐
2593 cuts for actions located on the macOS global menu bar, a full restart
2594 is needed. You can also map a keybinding to load a different config
2595 file, for example:
2596 map f5 load_config /path/to/alternative/kitty.conf
2598 Note that all options from the original kitty.conf are discarded, in
2600 other words the new configuration replace the old ones.
2601 Debug kitty configuration
2603 map ctrl+shift+f6 debug_config
2605 map opt+cmd+, debug_config 🍎
2606 Show details about exactly what configuration kitty is running with and
2608 its host environment. Useful for debugging issues.
2609 Send arbitrary text on key presses
2611 You can tell kitty to send arbitrary (UTF-8) encoded text to the client
2613 program when pressing specified shortcut keys. For example:
2614 map ctrl+alt+a send_text all Special text
2616 This will send "Special text" when you press the Ctrl+Alt+A key combi‐
2618 nation. The text to be sent decodes ANSI C escapes so you can use es‐
2619 capes like \e to send control codes or \u21fb to send Unicode charac‐
2620 ters (or you can just input the Unicode characters directly as UTF-8
2621 text). You can use kitten show_key to get the key escape codes you want
2622 to emulate.
2623 The first argument to send_text is the keyboard modes in which to acti‐
2625 vate the shortcut. The possible values are normal, application, kitty
2626 or a comma separated combination of them. The modes normal and appli‐
2627 cation refer to the DECCKM cursor key mode for terminals, and kitty
2628 refers to the kitty extended keyboard protocol. The special value all
2629 means all of them.
2630 Some more examples:
2632 # Output a word and move the cursor to the start of the line (like typing and pressing Home)
2634 map ctrl+alt+a send_text normal Word\e[H
2635 map ctrl+alt+a send_text application Word\eOH
2636 # Run a command at a shell prompt (like typing the command and pressing Enter)
2637 map ctrl+alt+a send_text normal,application some command with arguments\r
2638 Open kitty Website
2640 map shift+cmd+/ open_url https://sw.kovidgoyal.net/kitty/ 🍎
2642 Hide macOS kitty application
2644 map cmd+h hide_macos_app 🍎
2646 Hide macOS other applications
2648 map opt+cmd+h hide_macos_other_apps 🍎
2650 Minimize macOS window
2652 map cmd+m minimize_macos_window 🍎
2654 Quit kitty
2656 map cmd+q quit 🍎
2658
2660 You can edit a fully commented sample kitty.conf by pressing the
2661 ctrl+shift+f2 shortcut in kitty. This will generate a config file with
2662 full documentation and all settings commented out. If you have a
2663 pre-existing kitty.conf, then that will be used instead, delete it to
2664 see the sample file.
2665 A default configuration file can also be generated by running:
2667 kitty +runpy 'from kitty.config import *; print(commented_out_default_config())'
2669 This will print the commented out default config file to STDOUT.
2671
2673 See the list of all the things you can make kitty can do.
2674 Mappable actions
2676 The actions described below can be mapped to any key press or mouse ac‐
2677 tion using the map and mouse_map directives in kitty.conf. For configu‐
2678 ration examples, see the default shortcut links for each action.
2679 Copy/paste
2681 clear_selection
2682 Clear the current selection
2684 copy_and_clear_or_interrupt
2686 Copy the selected text from the active window to the clipboard and
2688 clear selection, if no selection, send SIGINT (aka ctrl+c)
2689 copy_ansi_to_clipboard
2691 Copy the selected text from the active window to the clipboard with
2693 ANSI formatting codes
2694 copy_or_interrupt
2696 Copy the selected text from the active window to the clipboard, if no
2698 selection, send SIGINT (aka ctrl+c)
2699 copy_to_clipboard
2701 Copy the selected text from the active window to the clipboard
2703 Default shortcuts using this action: ctrl+shift+c
2705 pass_selection_to_program
2707 Pass the selected text from the active window to the specified program
2709 Default shortcuts using this action: ctrl+shift+o
2711 paste
2713 Paste the specified text into the current window. ANSI C escapes are
2715 decoded.
2716 show_first_command_output_on_screen
2718 Show output from the first shell command on screen in a pager like less
2720 Requires Shell integration to work
2722 show_last_command_output
2724 Show output from the last shell command in a pager like less
2726 Requires Shell integration to work
2728 Default shortcuts using this action: ctrl+shift+g
2730 show_last_non_empty_command_output
2732 Show the last non-empty output from a shell command in a pager like
2734 less
2735 Requires Shell integration to work
2737 show_last_visited_command_output
2739 Show the first command output below the last scrolled position via
2741 scroll_to_prompt
2742 or the last mouse clicked command output in a pager like less
2744 Requires Shell integration to work
2746 show_scrollback
2748 Show scrollback in a pager like less
2750 Default shortcuts using this action: ctrl+shift+h
2752 copy_to_buffer
2754 Copy the selection from the active window to the specified buffer
2756 See Multiple copy/paste buffers for details.
2758 paste_from_buffer
2760 Paste from the specified buffer to the active window
2762 See Multiple copy/paste buffers for details.
2764 paste_from_clipboard
2766 Paste from the clipboard to the active window
2768 Default shortcuts using this action: ctrl+shift+v
2770 paste_from_selection
2772 Paste from the primary selection, if present, otherwise the clipboard
2774 to the active window
2775 Default shortcuts using this action: ctrl+shift+s
2777 Debugging
2779 dump_lines_with_attrs
2780 Show a dump of the current lines in the scrollback + screen with their
2782 line attributes
2783 close_shared_ssh_connections
2785 Close all shared SSH connections
2787 See share_connections for details.
2789 debug_config
2791 Show the effective configuration kitty is running with
2793 Default shortcuts using this action: ctrl+shift+f6
2795 show_kitty_env_vars
2797 Show the environment variables that the kitty process sees
2799 Layouts
2801 goto_layout
2802 Switch to the named layout
2804 In case there are multiple layouts with the same name and different op‐
2806 tions, specify the full layout definition or a unique prefix of the
2807 full definition.
2808 For example:
2810 map f1 goto_layout tall
2812 map f2 goto_layout fat:bias=20
2813 last_used_layout
2815 Go to the previously used layout
2817 layout_action
2819 Perform a layout specific action. See Arrange windows for details
2821 next_layout
2823 Go to the next enabled layout. Can optionally supply an integer to jump
2825 by the specified number.
2826 Default shortcuts using this action: ctrl+shift+l
2828 toggle_layout
2830 Toggle the named layout
2832 Switches to the named layout if another layout is current, otherwise
2834 switches to the last used layout. Useful to "zoom" a window temporarily
2835 by switching to the stack layout. For example:
2836 map f1 toggle_layout stack
2838 Marks
2840 remove_marker
2841 Remove a previously created marker
2843 scroll_to_mark
2845 Scroll to the next or previous mark of the specified type
2847 toggle_marker
2849 Toggle the current marker on/off
2851 create_marker
2853 Create a new marker
2855 Miscellaneous
2857 send_text
2858 Send the specified text to the active window
2860 See send_text for details.
2862 Default shortcuts using this action: ctrl+shift+alt+h
2864 show_kitty_doc
2866 Display the specified kitty documentation, preferring a local copy, if
2868 found.
2869 For example:
2871 # show the config docs
2873 map f1 show_kitty_doc conf
2874 # show the ssh kitten docs
2875 map f1 show_kitty_doc kittens/ssh
2876 Default shortcuts using this action: ctrl+shift+f1
2878 signal_child
2880 Send the specified SIGNAL to the foreground process in the active win‐
2882 dow
2883 For example:
2885 map f1 signal_child SIGTERM
2887 clear_terminal
2889 Clear the terminal
2891 See reset_terminal for details. For example:
2893 # Reset the terminal
2895 map f1 clear_terminal reset active
2896 # Clear the terminal screen by erasing all contents
2897 map f1 clear_terminal clear active
2898 # Clear the terminal scrollback by erasing it
2899 map f1 clear_terminal scrollback active
2900 # Scroll the contents of the screen into the scrollback
2901 map f1 clear_terminal scroll active
2902 # Clear everything up to the line with the cursor
2903 map f1 clear_terminal to_cursor active
2904 Default shortcuts using this action: cmd+k, ctrl+shift+delete
2906 combine
2908 Combine multiple actions and map to a single keypress
2910 The syntax is:
2912 map key combine <separator> action1 <separator> action2 <separator> action3 ...
2914 For example:
2916 map kitty_mod+e combine : new_window : next_layout
2918 disable_ligatures_in
2920 Turn on/off ligatures in the specified window
2922 See disable_ligatures for details
2924 discard_event
2926 Discard this event completely ignoring it
2928 edit_config_file
2930 Edit the kitty.conf config file in your favorite text editor
2932 Default shortcuts using this action: ctrl+shift+f2
2934 hide_macos_app
2936 Hide macOS kitty application
2938 Default shortcuts using this action: cmd+h
2940 hide_macos_other_apps
2942 Hide macOS other applications
2944 Default shortcuts using this action: opt+cmd+h
2946 input_unicode_character
2948 Input an arbitrary unicode character. See Unicode input for details.
2950 kitten
2952 Run the specified kitten. See Custom kittens for details
2954 Default shortcuts using this action:
2956 • Hints - ctrl+shift+p>h Insert selected hash
2958 • Hints - ctrl+shift+p>l Insert selected line
2960 • Hints - ctrl+shift+p>f Insert selected path
2962 • Hints - ctrl+shift+p>w Insert selected word
2964 • Hints - ctrl+shift+p>shift+f Open selected path
2966 • Hints - ctrl+shift+p>n Open the selected file at the selected line
2968 • Hints - ctrl+shift+p>y Open the selected hyperlink
2970 • Unicode input - ctrl+shift+u Unicode input
2972 kitty_shell
2974 Run the kitty shell to control kitty with commands
2976 Default shortcuts using this action: ctrl+shift+escape
2978 launch
2980 Launch the specified program in a new window/tab/etc.
2982 See The launch command for details
2984 load_config_file
2986 Reload the config file
2988 If mapped without arguments reloads the default config file, otherwise
2990 loads the specified config files, in order. Loading a config file re‐
2991 places all config options. For example:
2992 map f5 load_config_file /path/to/some/kitty.conf
2994 Default shortcuts using this action: ctrl+shift+f5
2996 minimize_macos_window
2998 Minimize macOS window
3000 Default shortcuts using this action: cmd+m
3002 open_url
3004 Open the specified URL
3006 Default shortcuts using this action: shift+cmd+/
3008 open_url_with_hints
3010 Click a URL using the keyboard
3012 Default shortcuts using this action: ctrl+shift+e
3014 remote_control
3016 Run a remote control command without needing to allow remote control
3018 For example:
3020 map f1 remote_control set-spacing margin=30
3022 See Mapping key presses to remote control commands for details.
3024 remote_control_script
3026 Run a remote control script without needing to allow remote control
3028 For example:
3030 map f1 remote_control_script arg1 arg2 ...
3032 See Mapping key presses to remote control commands for details.
3034 set_colors
3036 Change colors in the specified windows
3038 For details, see kitten @ set-colors. For example:
3040 map f5 set_colors --configured /path/to/some/config/file/colors.conf
3042 sleep
3044 Sleep for the specified time period. Suffix can be s for seconds, m,
3046 for minutes, h for hours and d for days. The time can be fractional.
3047 toggle_macos_secure_keyboard_entry
3049 Toggle macOS secure keyboard entry
3051 Default shortcuts using this action: opt+cmd+s
3053 no_op
3055 Unbind a shortcut
3057 Mapping a shortcut to no_op causes kitty to not intercept the key
3059 stroke anymore, instead passing it to the program running inside it.
3060 Mouse actions
3062 mouse_click_url
3063 Click the URL under the mouse
3065 mouse_click_url_or_select
3067 Click the URL under the mouse only if the screen has no selection
3069 mouse_handle_click
3071 Handle a mouse click
3073 Try to perform the specified actions one after the other till one of
3075 them is successful. Supported actions are:
3076 selection - check for a selection and if one exists abort processing
3078 link - if a link exists under the mouse, click it
3079 prompt - if the mouse click happens at a shell prompt move the cursor to the mouse location
3080 For examples, see Mouse actions
3082 mouse_select_command_output
3084 Select clicked command output
3086 Requires Shell integration to work
3088 mouse_selection
3090 Manipulate the selection based on the current mouse position
3092 For examples, see Mouse actions
3094 mouse_show_command_output
3096 Show clicked command output in a pager like less
3098 Requires Shell integration to work
3100 paste_selection
3102 Paste the current primary selection
3104 paste_selection_or_clipboard
3106 Paste the current primary selection or the clipboard if no selection is
3108 present
3109 Scrolling
3111 scroll_end
3112 Scroll to the bottom of the scrollback buffer when in main screen
3114 Default shortcuts using this action: ctrl+shift+end
3116 scroll_home
3118 Scroll to the top of the scrollback buffer when in main screen
3120 Default shortcuts using this action: ctrl+shift+home
3122 scroll_line_down
3124 Scroll down by one line when in main screen
3126 Default shortcuts using this action: ctrl+shift+down
3128 scroll_line_up
3130 Scroll up by one line when in main screen
3132 Default shortcuts using this action: ctrl+shift+up
3134 scroll_page_down
3136 Scroll down by one page when in main screen
3138 Default shortcuts using this action: ctrl+shift+page_down
3140 scroll_page_up
3142 Scroll up by one page when in main screen
3144 Default shortcuts using this action: ctrl+shift+page_up
3146 scroll_prompt_to_bottom
3148 Scroll prompt to the bottom of the screen, filling in extra lines from
3150 the scrollback buffer, when in main screen
3151 scroll_prompt_to_top
3153 Scroll prompt to the top of the screen, filling screen with empty
3155 lines, when in main screen
3156 scroll_to_prompt
3158 Scroll to the previous/next shell command prompt
3160 Allows easy jumping from one command to the next. Requires working
3162 Shell integration. Takes a single, optional, number as argument which
3163 is the number of prompts to jump, negative values jump up and positive
3164 values jump down. A value of zero will jump to the last prompt visited
3165 by this action. For example:
3166 map ctrl+p scroll_to_prompt -1 # jump to previous
3168 map ctrl+n scroll_to_prompt 1 # jump to next
3169 map ctrl+o scroll_to_prompt 0 # jump to last visited
3170 Default shortcuts using this action: ctrl+shift+x, ctrl+shift+z
3172 Tab management
3174 close_other_tabs_in_os_window
3175 Close all the tabs in the current OS window other than the currently
3177 active tab
3178 close_tab
3180 Close the current tab
3182 Default shortcuts using this action: ctrl+shift+q
3184 detach_tab
3186 Detach a tab, moving it to another OS Window
3188 See detaching windows for details.
3190 goto_tab
3192 Go to the specified tab, by number, starting with 1
3194 Zero and negative numbers go to previously active tabs
3196 move_tab_backward
3198 Move the active tab backward
3200 Default shortcuts using this action: ctrl+shift+,
3202 move_tab_forward
3204 Move the active tab forward
3206 Default shortcuts using this action: ctrl+shift+.
3208 new_tab
3210 Create a new tab
3212 Default shortcuts using this action: ctrl+shift+t
3214 new_tab_with_cwd
3216 Create a new tab with working directory for the window in it set to the
3218 same as the active window
3219 next_tab
3221 Make the next tab active
3223 Default shortcuts using this action: ctrl+shift+right
3225 previous_tab
3227 Make the previous tab active
3229 Default shortcuts using this action: ctrl+shift+left
3231 select_tab
3233 Interactively select a tab to switch to
3235 set_tab_title
3237 Change the title of the active tab interactively, by typing in the new
3239 title.
3240 If you specify an argument to this action then that is used as the ti‐
3242 tle instead of asking for it. Use the empty string ("") to reset the
3243 title to default. Use a space (" ") to indicate that the prompt should
3244 not be pre-filled. For example:
3245 # interactive usage
3247 map f1 set_tab_title
3248 # set a specific title
3249 map f2 set_tab_title some title
3250 # reset to default
3251 map f3 set_tab_title ""
3252 # interactive usage without prefilled prompt
3253 map f3 set_tab_title " "
3254 Default shortcuts using this action: ctrl+shift+alt+t
3256 Window management
3258 set_window_title
3259 Change the title of the active window interactively, by typing in the
3261 new title.
3262 If you specify an argument to this action then that is used as the ti‐
3264 tle instead of asking for it. Use the empty string ("") to reset the
3265 title to default. Use a space (" ") to indicate that the prompt should
3266 not be pre-filled. For example:
3267 # interactive usage
3269 map f1 set_window_title
3270 # set a specific title
3271 map f2 set_window_title some title
3272 # reset to default
3273 map f3 set_window_title ""
3274 # interactive usage without prefilled prompt
3275 map f3 set_window_title " "
3276 close_other_windows_in_tab
3278 Close all windows in the tab other than the currently active window
3280 eighth_window
3282 Focus the eighth window
3284 Default shortcuts using this action: ctrl+shift+8
3286 fifth_window
3288 Focus the fifth window
3290 Default shortcuts using this action: ctrl+shift+5
3292 first_window
3294 Focus the first window
3296 Default shortcuts using this action: ctrl+shift+1
3298 focus_visible_window
3300 Focus a visible window by pressing the number of the window. Window
3302 numbers are displayed
3303 over the windows for easy selection in this mode. See
3305 visual_window_select_characters.
3306 Default shortcuts using this action: ctrl+shift+f7
3308 fourth_window
3310 Focus the fourth window
3312 Default shortcuts using this action: ctrl+shift+4
3314 move_window
3316 Move the window in the specified direction
3318 For example:
3320 map ctrl+left move_window left
3322 map ctrl+down move_window bottom
3323 move_window_backward
3325 Move active window backward (swap it with the previous window)
3327 Default shortcuts using this action: ctrl+shift+b
3329 move_window_forward
3331 Move active window forward (swap it with the next window)
3333 Default shortcuts using this action: ctrl+shift+f
3335 move_window_to_top
3337 Move active window to the top (make it the first window)
3339 Default shortcuts using this action: ctrl+shift+`
3341 neighboring_window
3343 Focus the neighboring window in the current tab
3345 For example:
3347 map ctrl+left neighboring_window left
3349 map ctrl+down neighboring_window bottom
3350 next_window
3352 Focus the next window in the current tab
3354 Default shortcuts using this action: ctrl+shift+]
3356 ninth_window
3358 Focus the ninth window
3360 Default shortcuts using this action: ctrl+shift+9
3362 nth_window
3364 Focus the nth window if positive or the previously active windows if
3366 negative. When the number is larger
3367 than the number of windows focus the last window. For example:
3369 # focus the previously active window
3371 map ctrl+p nth_window -1
3372 # focus the first window
3373 map ctrl+1 nth_window 0
3374 previous_window
3376 Focus the previous window in the current tab
3378 Default shortcuts using this action: ctrl+shift+[
3380 reset_window_sizes
3382 Reset window sizes undoing any dynamic resizing of windows
3384 resize_window
3386 Resize the active window by the specified amount
3388 See Resizing windows for details.
3390 second_window
3392 Focus the second window
3394 Default shortcuts using this action: ctrl+shift+2
3396 seventh_window
3398 Focus the seventh window
3400 Default shortcuts using this action: ctrl+shift+7
3402 sixth_window
3404 Focus the sixth window
3406 Default shortcuts using this action: ctrl+shift+6
3408 swap_with_window
3410 Swap the current window with another window in the current tab, se‐
3412 lected visually. See visual_window_select_characters
3413 Default shortcuts using this action: ctrl+shift+f8
3415 tenth_window
3417 Focus the tenth window
3419 Default shortcuts using this action: ctrl+shift+0
3421 third_window
3423 Focus the third window
3425 Default shortcuts using this action: ctrl+shift+3
3427 change_font_size
3429 Change the font size for the current or all OS Windows
3431 See Font sizes for details.
3433 Default shortcuts using this action: ctrl+shift+minus,
3435 ctrl+shift+equal, ctrl+shift+backspace
3436 close_os_window
3438 Close the currently active OS Window
3440 Default shortcuts using this action: shift+cmd+w
3442 close_window
3444 Close the currently active window
3446 Default shortcuts using this action: ctrl+shift+w
3448 close_window_with_confirmation
3450 Close window with confirmation
3452 Asks for confirmation before closing the window. If you don't want the
3454 confirmation when the window is sitting at a shell prompt (requires
3455 Shell integration), use:
3456 map f1 close_window_with_confirmation ignore-shell
3458 detach_window
3460 Detach a window, moving it to another tab or OS Window
3462 See detaching windows for details.
3464 new_os_window
3466 New OS Window
3468 Default shortcuts using this action: ctrl+shift+n
3470 new_os_window_with_cwd
3472 New OS Window with the same working directory as the currently active
3474 window
3475 new_window
3477 Create a new window
3479 Default shortcuts using this action: ctrl+shift+enter
3481 new_window_with_cwd
3483 Create a new window with working directory same as that of the active
3485 window
3486 nth_os_window
3488 Focus the nth OS window
3490 quit
3492 Quit, closing all windows
3494 Default shortcuts using this action: cmd+q
3496 set_background_opacity
3498 Set the background opacity for the active OS Window
3500 For example:
3502 map f1 set_background_opacity +0.1
3504 map f2 set_background_opacity -0.1
3505 map f3 set_background_opacity 0.5
3506 Default shortcuts using this action: ctrl+shift+a>l, ctrl+shift+a>1,
3508 ctrl+shift+a>m, ctrl+shift+a>d
3509 start_resizing_window
3511 Resize the active window interactively
3513 See Resizing windows for details.
3515 Default shortcuts using this action: ctrl+shift+r
3517 toggle_fullscreen
3519 Toggle the fullscreen status of the active OS Window
3521 Default shortcuts using this action: ctrl+shift+f11
3523 toggle_maximized
3525 Toggle the maximized status of the active OS Window
3527 Default shortcuts using this action: ctrl+shift+f10
3529
3531 Kovid Goyal
3532
3534 2023, Kovid Goyal
35350.31.0 Nov 08, 2023 KITTY.CONF(5)