1KITTY.CONF(5) kitty KITTY.CONF(5)
2
6 kitty.conf - kitty.conf Documentation
7 kitty is highly customizable, everything from keyboard shortcuts, to
9 rendering frames-per-second. See below for an overview of all cus‐
10 tomization possibilities.
11 You can open the config file within kitty by pressing ctrl+shift+f2
13 (⌘+, on macOS). A kitty.conf with commented default configurations and
14 descriptions will be created if the file does not exist. You can
15 reload the config file within kitty by pressing ctrl+shift+f5 (⌃+⌘+, on
16 macOS) or sending kitty the SIGUSR1 signal. You can also display the
17 current configuration by pressing ctrl+shift+f6 (⌥+⌘+, on macOS).
18 kitty looks for a config file in the OS config directories (usually
20 ~/.config/kitty/kitty.conf) but you can pass a specific path via the
21 kitty --config option or use the KITTY_CONFIG_DIRECTORY environment
22 variable. See kitty --config for full details.
23 Comments can be added to the config file as lines starting with the #
25 character. This works only if the # character is the first character in
26 the line.
27 You can include secondary config files via the include directive. If
29 you use a relative path for include, it is resolved with respect to the
30 location of the current config file. Note that environment variables
31 are expanded, so ${USER}.conf becomes name.conf if USER=name. Also, you
32 can use globinclude to include files matching a shell glob pattern and
33 envinclude to include configuration from environment variables. For ex‐
34 ample:
35 include other.conf
37 # Include *.conf files from all subdirs of kitty.d inside the kitty config dir
38 globinclude kitty.d/**/*.conf
39 # Include the *contents* of all env vars starting with KITTY_CONF_
40 envinclude KITTY_CONF_*
41 NOTE:
43 Syntax highlighting for kitty.conf in vim is available via
44 vim-kitty.
45 kitty has very powerful font management. You can configure individual
47 font faces and even specify special fonts for particular characters.
48 font_family, bold_font, italic_font, bold_italic_font
50 font_family monospace
52 bold_font auto
53 italic_font auto
54 bold_italic_font auto
55 You can specify different fonts for the bold/italic/bold-italic vari‐
57 ants. To get a full list of supported fonts use the kitty +list-fonts
58 command. By default they are derived automatically, by the OSes font
59 system. When bold_font or bold_italic_font is set to auto on macOS, the
60 priority of bold fonts is semi-bold, bold, heavy. Setting them manually
61 is useful for font families that have many weight variants like Book,
62 Medium, Thick, etc. For example:
63 font_family Operator Mono Book
65 bold_font Operator Mono Medium
66 italic_font Operator Mono Book Italic
67 bold_italic_font Operator Mono Medium Italic
68 font_size
70 font_size 11.0
72 Font size (in pts)
74 force_ltr
76 force_ltr no
78 kitty does not support BIDI (bidirectional text), however, for RTL
80 scripts, words are automatically displayed in RTL. That is to say, in
81 an RTL script, the words "HELLO WORLD" display in kitty as "WORLD
82 HELLO", and if you try to select a substring of an RTL-shaped string,
83 you will get the character that would be there had the the string been
84 LTR. For example, assuming the Hebrew word ירושלים, selecting the char‐
85 acter that on the screen appears to be ם actually writes into the se‐
86 lection buffer the character י. kitty's default behavior is useful in
87 conjunction with a filter to reverse the word order, however, if you
88 wish to manipulate RTL glyphs, it can be very challenging to work with,
89 so this option is provided to turn it off. Furthermore, this option can
90 be used with the command line program GNU FriBidi to get BIDI support,
91 because it will force kitty to always treat the text as LTR, which
92 FriBidi expects for terminals.
93 symbol_map
95 symbol_map U+E0A0-U+E0A3,U+E0C0-U+E0C7 PowerlineSymbols
97 Map the specified Unicode codepoints to a particular font. Useful if
99 you need special rendering for some symbols, such as for Powerline.
100 Avoids the need for patched fonts. Each Unicode code point is specified
101 in the form U+<code point in hexadecimal>. You can specify multiple
102 code points, separated by commas and ranges separated by hyphens. This
103 option can be specified multiple times. The syntax is:
104 symbol_map codepoints Font Family Name
106 narrow_symbols
108 narrow_symbols U+E0A0-U+E0A3,U+E0C0-U+E0C7 1
110 Usually, for Private Use Unicode characters and some symbol/dingbat
112 characters, if the character is followed by one or more spaces, kitty
113 will use those extra cells to render the character larger, if the char‐
114 acter in the font has a wide aspect ratio. Using this option you can
115 force kitty to restrict the specified code points to render in the
116 specified number of cells (defaulting to one cell). This option can be
117 specified multiple times. The syntax is:
118 narrow_symbols codepoints [optionally the number of cells]
120 disable_ligatures
122 disable_ligatures never
124 Choose how you want to handle multi-character ligatures. The default is
126 to always render them. You can tell kitty to not render them when the
127 cursor is over them by using cursor to make editing easier, or have
128 kitty never render them at all by using always, if you don't like them.
129 The ligature strategy can be set per-window either using the kitty re‐
130 mote control facility or by defining shortcuts for it in kitty.conf,
131 for example:
132 map alt+1 disable_ligatures_in active always
134 map alt+2 disable_ligatures_in all never
135 map alt+3 disable_ligatures_in tab cursor
136 Note that this refers to programming ligatures, typically implemented
138 using the calt OpenType feature. For disabling general ligatures, use
139 the font_features option.
140 font_features
142 font_features none
144 Choose exactly which OpenType features to enable or disable. This is
146 useful as some fonts might have features worthwhile in a terminal. For
147 example, Fira Code includes a discretionary feature, zero, which in
148 that font changes the appearance of the zero (0), to make it more eas‐
149 ily distinguishable from Ø. Fira Code also includes other discretionary
150 features known as Stylistic Sets which have the tags ss01 through ss20.
151 For the exact syntax to use for individual features, see the HarfBuzz
153 documentation.
154 Note that this code is indexed by PostScript name, and not the font
156 family. This allows you to define very precise feature settings; e.g.
157 you can disable a feature in the italic font but not in the regular
158 font.
159 On Linux, font features are first read from the FontConfig database and
161 then this option is applied, so they can be configured in a single,
162 central place.
163 To get the PostScript name for a font, use kitty +list-fonts --psnames:
165 $ kitty +list-fonts --psnames | grep Fira
167 Fira Code
168 Fira Code Bold (FiraCode-Bold)
169 Fira Code Light (FiraCode-Light)
170 Fira Code Medium (FiraCode-Medium)
171 Fira Code Regular (FiraCode-Regular)
172 Fira Code Retina (FiraCode-Retina)
173 The part in brackets is the PostScript name.
175 Enable alternate zero and oldstyle numerals:
177 font_features FiraCode-Retina +zero +onum
179 Enable only alternate zero in the bold font:
181 font_features FiraCode-Bold +zero
183 Disable the normal ligatures, but keep the calt feature which (in this
185 font) breaks up monotony:
186 font_features TT2020StyleB-Regular -liga +calt
188 In conjunction with force_ltr, you may want to disable Arabic shaping
190 entirely, and only look at their isolated forms if they show up in a
191 document. You can do this with e.g.:
192 font_features UnifontMedium +isol -medi -fina -init
194 modify_font
196 modify_font
198 Modify font characteristics such as the position or thickness of the
200 underline and strikethrough. The modifications can have the suffix px
201 for pixels or % for percentage of original value. No suffix means use
202 pts. For example:
203 modify_font underline_position -2
205 modify_font underline_thickness 150%
206 modify_font strikethrough_position 2px
207 Additionally, you can modify the size of the cell in which each font
209 glyph is rendered and the baseline at which the glyph is placed in the
210 cell. For example:
211 modify_font cell_width 80%
213 modify_font cell_height -2px
214 modify_font baseline 3
215 Note that modifying the baseline will automatically adjust the under‐
217 line and strikethrough positions by the same amount. Increasing the
218 baseline raises glyphs inside the cell and decreasing it lowers them.
219 Decreasing the cell size might cause rendering artifacts, so use with
220 care.
221 box_drawing_scale
223 box_drawing_scale 0.001, 1, 1.5, 2
225 The sizes of the lines used for the box drawing Unicode characters.
227 These values are in pts. They will be scaled by the monitor DPI to ar‐
228 rive at a pixel value. There must be four values corresponding to
229 thin, normal, thick, and very thick lines.
230 cursor
232 cursor #cccccc
234 Default cursor color. If set to the special value none the cursor will
236 be rendered with a "reverse video" effect. It's color will be the color
237 of the text in the cell it is over and the text will be rendered with
238 the background color of the cell. Note that if the program running in
239 the terminal sets a cursor color, this takes precedence. Also, the cur‐
240 sor colors are modified if the cell background and foreground colors
241 have very low contrast.
242 cursor_text_color
244 cursor_text_color #111111
246 The color of text under the cursor. If you want it rendered with the
248 background color of the cell underneath instead, use the special key‐
249 word: background. Note that if cursor is set to none then this option
250 is ignored.
251 cursor_shape
253 cursor_shape block
255 The cursor shape can be one of block, beam, underline. Note that when
257 reloading the config this will be changed only if the cursor shape has
258 not been set by the program running in the terminal. This sets the de‐
259 fault cursor shape, applications running in the terminal can override
260 it. In particular, shell integration in kitty sets the cursor shape to
261 beam at shell prompts. You can avoid this by setting shell_integration
262 to no-cursor.
263 cursor_beam_thickness
265 cursor_beam_thickness 1.5
267 The thickness of the beam cursor (in pts).
269 cursor_underline_thickness
271 cursor_underline_thickness 2.0
273 The thickness of the underline cursor (in pts).
275 cursor_blink_interval
277 cursor_blink_interval -1
279 The interval to blink the cursor (in seconds). Set to zero to disable
281 blinking. Negative values mean use system default. Note that the mini‐
282 mum interval will be limited to repaint_delay.
283 cursor_stop_blinking_after
285 cursor_stop_blinking_after 15.0
287 Stop blinking cursor after the specified number of seconds of keyboard
289 inactivity. Set to zero to never stop blinking.
290 scrollback_lines
292 scrollback_lines 2000
294 Number of lines of history to keep in memory for scrolling back. Memory
296 is allocated on demand. Negative numbers are (effectively) infinite
297 scrollback. Note that using very large scrollback is not recommended
298 as it can slow down performance of the terminal and also use large
299 amounts of RAM. Instead, consider using scrollback_pager_history_size.
300 Note that on config reload if this is changed it will only affect newly
301 created windows, not existing ones.
302 scrollback_pager
304 scrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS +INPUT_LINE_NUMBER
306 Program with which to view scrollback in a new window. The scrollback
308 buffer is passed as STDIN to this program. If you change it, make sure
309 the program you use can handle ANSI escape sequences for colors and
310 text formatting. INPUT_LINE_NUMBER in the command line above will be
311 replaced by an integer representing which line should be at the top of
312 the screen. Similarly CURSOR_LINE and CURSOR_COLUMN will be replaced by
313 the current cursor position or set to 0 if there is no cursor, for ex‐
314 ample, when showing the last command output.
315 scrollback_pager_history_size
317 scrollback_pager_history_size 0
319 Separate scrollback history size (in MB), used only for browsing the
321 scrollback buffer with pager. This separate buffer is not available for
322 interactive scrolling but will be piped to the pager program when view‐
323 ing scrollback buffer in a separate window. The current implementation
324 stores the data in UTF-8, so approximatively 10000 lines per megabyte
325 at 100 chars per line, for pure ASCII, unformatted text. A value of
326 zero or less disables this feature. The maximum allowed size is 4GB.
327 Note that on config reload if this is changed it will only affect newly
328 created windows, not existing ones.
329 scrollback_fill_enlarged_window
331 scrollback_fill_enlarged_window no
333 Fill new space with lines from the scrollback buffer after enlarging a
335 window.
336 wheel_scroll_multiplier
338 wheel_scroll_multiplier 5.0
340 Multiplier for the number of lines scrolled by the mouse wheel. Note
342 that this is only used for low precision scrolling devices, not for
343 high precision scrolling devices on platforms such as macOS and Way‐
344 land. Use negative numbers to change scroll direction. See also
345 wheel_scroll_min_lines.
346 wheel_scroll_min_lines
348 wheel_scroll_min_lines 1
350 The minimum number of lines scrolled by the mouse wheel. The scroll
352 multiplier only takes effect after it reaches this number. Note that
353 this is only used for low precision scrolling devices like wheel mice
354 that scroll by very small amounts when using the wheel. With a negative
355 number, the minimum number of lines will always be added.
356 touch_scroll_multiplier
358 touch_scroll_multiplier 1.0
360 Multiplier for the number of lines scrolled by a touchpad. Note that
362 this is only used for high precision scrolling devices on platforms
363 such as macOS and Wayland. Use negative numbers to change scroll direc‐
364 tion.
365 mouse_hide_wait
367 mouse_hide_wait 3.0
369 Hide mouse cursor after the specified number of seconds of the mouse
371 not being used. Set to zero to disable mouse cursor hiding. Set to a
372 negative value to hide the mouse cursor immediately when typing text.
373 Disabled by default on macOS as getting it to work robustly with the
374 ever-changing sea of bugs that is Cocoa is too much effort.
375 url_color, url_style
377 url_color #0087bd
379 url_style curly
380 The color and style for highlighting URLs on mouse-over. url_style can
382 be one of: none, straight, double, curly, dotted, dashed.
383 open_url_with
385 open_url_with default
387 The program to open clicked URLs. The special value default with first
389 look for any URL handlers defined via the Scripting the mouse click fa‐
390 cility and if non are found, it will use the Operating System's default
391 URL handler (open on macOS and xdg-open on Linux).
392 url_prefixes
394 url_prefixes file ftp ftps gemini git gopher http https irc ircs kitty mailto news sftp ssh
396 The set of URL prefixes to look for when detecting a URL under the
398 mouse cursor.
399 detect_urls
401 detect_urls yes
403 Detect URLs under the mouse. Detected URLs are highlighted with an un‐
405 derline and the mouse cursor becomes a hand over them. Even if this op‐
406 tion is disabled, URLs are still clickable.
407 url_excluded_characters
409 url_excluded_characters
411 Additional characters to be disallowed from URLs, when detecting URLs
413 under the mouse cursor. By default, all characters that are legal in
414 URLs are allowed.
415 copy_on_select
417 copy_on_select no
419 Copy to clipboard or a private buffer on select. With this set to clip‐
421 board, selecting text with the mouse will cause the text to be copied
422 to clipboard. Useful on platforms such as macOS that do not have the
423 concept of primary selection. You can instead specify a name such as a1
424 to copy to a private kitty buffer. Map a shortcut with the
425 paste_from_buffer action to paste from this private buffer. For exam‐
426 ple:
427 copy_on_select a1
429 map shift+cmd+v paste_from_buffer a1
430 Note that copying to the clipboard is a security risk, as all programs,
432 including websites open in your browser can read the contents of the
433 system clipboard.
434 paste_actions
436 paste_actions quote-urls-at-prompt
438 A comma separated list of actions to take when pasting text into the
440 terminal. The supported paste actions are:
441 quote-urls-at-prompt:
443 If the text being pasted is a URL and the cursor is at a shell
444 prompt, automatically quote the URL (needs shell_integration).
445 confirm:
447 Confirm the paste if bracketed paste mode is not active or there
448 is more a large amount of text being pasted.
449 filter:
451 Run the filter_paste() function from the file paste-actions.py
452 in the kitty config directory on the pasted text. The text re‐
453 turned by the function will be actually pasted.
454 strip_trailing_spaces
456 strip_trailing_spaces never
458 Remove spaces at the end of lines when copying to clipboard. A value of
460 smart will do it when using normal selections, but not rectangle selec‐
461 tions. A value of always will always do it.
462 select_by_word_characters
464 select_by_word_characters @-./_~?&=%+#
466 Characters considered part of a word when double clicking. In addition
468 to these characters any character that is marked as an alphanumeric
469 character in the Unicode database will be matched.
470 select_by_word_characters_forward
472 select_by_word_characters_forward
474 Characters considered part of a word when extending the selection for‐
476 ward on double clicking. In addition to these characters any character
477 that is marked as an alphanumeric character in the Unicode database
478 will be matched.
479 If empty (default) select_by_word_characters will be used for both di‐
481 rections.
482 click_interval
484 click_interval -1.0
486 The interval between successive clicks to detect double/triple clicks
488 (in seconds). Negative numbers will use the system default instead, if
489 available, or fallback to 0.5.
490 focus_follows_mouse
492 focus_follows_mouse no
494 Set the active window to the window under the mouse when moving the
496 mouse around.
497 pointer_shape_when_grabbed
499 pointer_shape_when_grabbed arrow
501 The shape of the mouse pointer when the program running in the terminal
503 grabs the mouse. Valid values are: arrow, beam and hand.
504 default_pointer_shape
506 default_pointer_shape beam
508 The default shape of the mouse pointer. Valid values are: arrow, beam
510 and hand.
511 pointer_shape_when_dragging
513 pointer_shape_when_dragging beam
515 The default shape of the mouse pointer when dragging across text. Valid
517 values are: arrow, beam and hand.
518
520 Mouse buttons can be mapped to perform arbitrary actions. The syntax
521 is:
522 mouse_map button-name event-type modes action
524 Where button-name is one of left, middle, right, b1 ... b8 with added
526 keyboard modifiers. For example: ctrl+shift+left refers to holding the
527 Ctrl+Shift keys while clicking with the left mouse button. The value b1
528 ... b8 can be used to refer to up to eight buttons on a mouse.
529 event-type is one of press, release, doublepress, triplepress, click,
531 doubleclick. modes indicates whether the action is performed when the
532 mouse is grabbed by the program running in the terminal, or not. The
533 values are grabbed or ungrabbed or a comma separated combination of
534 them. grabbed refers to when the program running in the terminal has
535 requested mouse events. Note that the click and double click events
536 have a delay of click_interval to disambiguate from double and triple
537 presses.
538 You can run kitty with the kitty --debug-input command line option to
540 see mouse events. See the builtin actions below to get a sense of what
541 is possible.
542 If you want to unmap an action, map it to no_op. For example, to dis‐
544 able opening of URLs with a plain click:
545 mouse_map left click ungrabbed no_op
547 See all the mappable actions including mouse actions here.
549 NOTE:
551 Once a selection is started, releasing the button that started it
552 will automatically end it and no release event will be dispatched.
553 clear_all_mouse_actions
555 clear_all_mouse_actions no
557 Remove all mouse action definitions up to this point. Useful, for in‐
559 stance, to remove the default mouse actions.
560 Click the link under the mouse or move the cursor
562 mouse_map left click ungrabbed mouse_handle_click selection link prompt
564 First check for a selection and if one exists do nothing. Then check
566 for a link under the mouse cursor and if one exists, click it. Finally
567 check if the click happened at the current shell prompt and if so, move
568 the cursor to the click location. Note that this requires shell inte‐
569 gration to work.
570 Click the link under the mouse or move the cursor even when grabbed
572 mouse_map shift+left click grabbed,ungrabbed mouse_handle_click selection link prompt
574 Same as above, except that the action is performed even when the mouse
576 is grabbed by the program running in the terminal.
577 Click the link under the mouse cursor
579 mouse_map ctrl+shift+left release grabbed,ungrabbed mouse_handle_click link
581 Variant with Ctrl+Shift is present because the simple click based ver‐
583 sion has an unavoidable delay of click_interval, to disambiguate clicks
584 from double clicks.
585 Discard press event for link click
587 mouse_map ctrl+shift+left press grabbed discard_event
589 Prevent this press event from being sent to the program that has
591 grabbed the mouse, as the corresponding release event is used to open a
592 URL.
593 Paste from the primary selection
595 mouse_map middle release ungrabbed paste_from_selection
597 Start selecting text
599 mouse_map left press ungrabbed mouse_selection normal
601 Start selecting text in a rectangle
603 mouse_map ctrl+alt+left press ungrabbed mouse_selection rectangle
605 Select a word
607 mouse_map left doublepress ungrabbed mouse_selection word
609 Select a line
611 mouse_map left triplepress ungrabbed mouse_selection line
613 Select line from point
615 mouse_map ctrl+alt+left triplepress ungrabbed mouse_selection line_from_point
617 Select from the clicked point to the end of the line.
619 Extend the current selection
621 mouse_map right press ungrabbed mouse_selection extend
623 If you want only the end of the selection to be moved instead of the
625 nearest boundary, use move-end instead of extend.
626 Paste from the primary selection even when grabbed
628 mouse_map shift+middle release ungrabbed,grabbed paste_selection
630 mouse_map shift+middle press grabbed discard_event
631 Start selecting text even when grabbed
633 mouse_map shift+left press ungrabbed,grabbed mouse_selection normal
635 Start selecting text in a rectangle even when grabbed
637 mouse_map ctrl+shift+alt+left press ungrabbed,grabbed mouse_selection rectangle
639 Select a word even when grabbed
641 mouse_map shift+left doublepress ungrabbed,grabbed mouse_selection word
643 Select a line even when grabbed
645 mouse_map shift+left triplepress ungrabbed,grabbed mouse_selection line
647 Select line from point even when grabbed
649 mouse_map ctrl+shift+alt+left triplepress ungrabbed,grabbed mouse_selection line_from_point
651 Select from the clicked point to the end of the line even when grabbed.
653 Extend the current selection even when grabbed
655 mouse_map shift+right press ungrabbed,grabbed mouse_selection extend
657 Show clicked command output in pager
659 mouse_map ctrl+shift+right press ungrabbed mouse_show_command_output
661 Requires shell integration to work.
663 repaint_delay
665 repaint_delay 10
667 Delay between screen updates (in milliseconds). Decreasing it, in‐
669 creases frames-per-second (FPS) at the cost of more CPU usage. The de‐
670 fault value yields ~100 FPS which is more than sufficient for most
671 uses. Note that to actually achieve 100 FPS, you have to either set
672 sync_to_monitor to no or use a monitor with a high refresh rate. Also,
673 to minimize latency when there is pending input to be processed, this
674 option is ignored.
675 input_delay
677 input_delay 3
679 Delay before input from the program running in the terminal is pro‐
681 cessed (in milliseconds). Note that decreasing it will increase respon‐
682 siveness, but also increase CPU usage and might cause flicker in full
683 screen programs that redraw the entire screen on each loop, because
684 kitty is so fast that partial screen updates will be drawn.
685 sync_to_monitor
687 sync_to_monitor yes
689 Sync screen updates to the refresh rate of the monitor. This prevents
691 screen tearing when scrolling. However, it limits the rendering speed
692 to the refresh rate of your monitor. With a very high speed mouse/high
693 keyboard repeat rate, you may notice some slight input latency. If so,
694 set this to no.
695 enable_audio_bell
697 enable_audio_bell yes
699 The audio bell. Useful to disable it in environments that require si‐
701 lence.
702 visual_bell_duration
704 visual_bell_duration 0.0
706 The visual bell duration (in seconds). Flash the screen when a bell oc‐
708 curs for the specified number of seconds. Set to zero to disable.
709 visual_bell_color
711 visual_bell_color none
713 The color used by visual bell. Set to none will fall back to selection
715 background color. If you feel that the visual bell is too bright, you
716 can set it to a darker color.
717 window_alert_on_bell
719 window_alert_on_bell yes
721 Request window attention on bell. Makes the dock icon bounce on macOS
723 or the taskbar flash on linux.
724 bell_on_tab
726 bell_on_tab "🔔 "
728 Some text or a Unicode symbol to show on the tab if a window in the tab
730 that does not have focus has a bell. If you want to use leading or
731 trailing spaces, surround the text with quotes. See tab_title_template
732 for how this is rendered.
733 For backwards compatibility, values of yes, y and true are converted to
735 the default bell symbol and no, n, false and none are converted to the
736 empty string.
737 command_on_bell
739 command_on_bell none
741 Program to run when a bell occurs. The environment variable
743 KITTY_CHILD_CMDLINE can be used to get the program running in the win‐
744 dow in which the bell occurred.
745 bell_path
747 bell_path none
749 Path to a sound file to play as the bell sound. If set to none, the
751 system default bell sound is used. Must be in a format supported by the
752 operating systems sound API, such as WAV or OGA on Linux (libcanberra)
753 or AIFF, MP3 or WAV on macOS (NSSound)
754 remember_window_size, initial_window_width, initial_window_height
756 remember_window_size yes
758 initial_window_width 640
759 initial_window_height 400
760 If enabled, the window size will be remembered so that new instances of
762 kitty will have the same size as the previous instance. If disabled,
763 the window will initially have size configured by initial_win‐
764 dow_width/height, in pixels. You can use a suffix of "c" on the
765 width/height values to have them interpreted as number of cells instead
766 of pixels.
767 enabled_layouts
769 enabled_layouts *
771 The enabled window layouts. A comma separated list of layout names. The
773 special value all means all layouts. The first listed layout will be
774 used as the startup layout. Default configuration is all layouts in al‐
775 phabetical order. For a list of available layouts, see the Layouts.
776 window_resize_step_cells, window_resize_step_lines
778 window_resize_step_cells 2
780 window_resize_step_lines 2
781 The step size (in units of cell width/cell height) to use when resizing
783 kitty windows in a layout with the shortcut ctrl+shift+r. The cells
784 value is used for horizontal resizing, and the lines value is used for
785 vertical resizing.
786 window_border_width
788 window_border_width 0.5pt
790 The width of window borders. Can be either in pixels (px) or pts (pt).
792 Values in pts will be rounded to the nearest number of pixels based on
793 screen resolution. If not specified, the unit is assumed to be pts.
794 Note that borders are displayed only when more than one window is visi‐
795 ble. They are meant to separate multiple windows.
796 draw_minimal_borders
798 draw_minimal_borders yes
800 Draw only the minimum borders needed. This means that only the borders
802 that separate the inactive window from a neighbor are drawn. Note that
803 setting a non-zero window_margin_width overrides this and causes all
804 borders to be drawn.
805 window_margin_width
807 window_margin_width 0
809 The window margin (in pts) (blank area outside the border). A single
811 value sets all four sides. Two values set the vertical and horizontal
812 sides. Three values set top, horizontal and bottom. Four values set
813 top, right, bottom and left.
814 single_window_margin_width
816 single_window_margin_width -1
818 The window margin to use when only a single window is visible (in pts).
820 Negative values will cause the value of window_margin_width to be used
821 instead. A single value sets all four sides. Two values set the verti‐
822 cal and horizontal sides. Three values set top, horizontal and bottom.
823 Four values set top, right, bottom and left.
824 window_padding_width
826 window_padding_width 0
828 The window padding (in pts) (blank area between the text and the window
830 border). A single value sets all four sides. Two values set the verti‐
831 cal and horizontal sides. Three values set top, horizontal and bottom.
832 Four values set top, right, bottom and left.
833 placement_strategy
835 placement_strategy center
837 When the window size is not an exact multiple of the cell size, the
839 cell area of the terminal window will have some extra padding on the
840 sides. You can control how that padding is distributed with this op‐
841 tion. Using a value of center means the cell area will be placed cen‐
842 trally. A value of top-left means the padding will be only at the bot‐
843 tom and right edges.
844 active_border_color
846 active_border_color #00ff00
848 The color for the border of the active window. Set this to none to not
850 draw borders around the active window.
851 inactive_border_color
853 inactive_border_color #cccccc
855 The color for the border of inactive windows.
857 bell_border_color
859 bell_border_color #ff5a00
861 The color for the border of inactive windows in which a bell has oc‐
863 curred.
864 inactive_text_alpha
866 inactive_text_alpha 1.0
868 Fade the text in inactive windows by the specified amount (a number be‐
870 tween zero and one, with zero being fully faded).
871 hide_window_decorations
873 hide_window_decorations no
875 Hide the window decorations (title-bar and window borders) with yes. On
877 macOS, titlebar-only can be used to only hide the titlebar. Whether
878 this works and exactly what effect it has depends on the window man‐
879 ager/operating system. Note that the effects of changing this option
880 when reloading config are undefined.
881 window_logo_path
883 window_logo_path none
885 Path to a logo image. Must be in PNG format. Relative paths are inter‐
887 preted relative to the kitty config directory. The logo is displayed in
888 a corner of every kitty window. The position is controlled by
889 window_logo_position. Individual windows can be configured to have
890 different logos either using the launch action or the remote control
891 facility.
892 window_logo_position
894 window_logo_position bottom-right
896 Where to position the window logo in the window. The value can be one
898 of: top-left, top, top-right, left, center, right, bottom-left, bottom,
899 bottom-right.
900 window_logo_alpha
902 window_logo_alpha 0.5
904 The amount the logo should be faded into the background. With zero be‐
906 ing fully faded and one being fully opaque.
907 resize_debounce_time
909 resize_debounce_time 0.1
911 The time to wait before redrawing the screen when a resize event is re‐
913 ceived (in seconds). On platforms such as macOS, where the operating
914 system sends events corresponding to the start and end of a resize,
915 this number is ignored.
916 resize_draw_strategy
918 resize_draw_strategy static
920 Choose how kitty draws a window while a resize is in progress. A value
922 of static means draw the current window contents, mostly unchanged. A
923 value of scale means draw the current window contents scaled. A value
924 of blank means draw a blank window. A value of size means show the win‐
925 dow size in cells.
926 resize_in_steps
928 resize_in_steps no
930 Resize the OS window in steps as large as the cells, instead of with
932 the usual pixel accuracy. Combined with initial_window_width and
933 initial_window_height in number of cells, this option can be used to
934 keep the margins as small as possible when resizing the OS window. Note
935 that this does not currently work on Wayland.
936 visual_window_select_characters
938 visual_window_select_characters 1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ
940 The list of characters for visual window selection. For example, for
942 selecting a window to focus on with ctrl+shift+f7. The value should be
943 a series of unique numbers or alphabets, case insensitive, from the set
944 [0-9A-Z]. Specify your preference as a string of characters.
945 confirm_os_window_close
947 confirm_os_window_close -1
949 Ask for confirmation when closing an OS window or a tab with at least
951 this number of kitty windows in it by window manager (e.g. clicking the
952 window close button or pressing the operating system shortcut to close
953 windows) or by the close_tab action. A value of zero disables confirma‐
954 tion. This confirmation also applies to requests to quit the entire ap‐
955 plication (all OS windows, via the quit action). Negative values are
956 converted to positive ones, however, with shell_integration enabled,
957 using negative values means windows sitting at a shell prompt are not
958 counted, only windows where some command is currently running. Note
959 that if you want confirmation when closing individual windows, you can
960 map the close_window_with_confirmation action.
961 tab_bar_edge
963 tab_bar_edge bottom
965 The edge to show the tab bar on, top or bottom.
967 tab_bar_margin_width
969 tab_bar_margin_width 0.0
971 The margin to the left and right of the tab bar (in pts).
973 tab_bar_margin_height
975 tab_bar_margin_height 0.0 0.0
977 The margin above and below the tab bar (in pts). The first number is
979 the margin between the edge of the OS Window and the tab bar. The sec‐
980 ond number is the margin between the tab bar and the contents of the
981 current tab.
982 tab_bar_style
984 tab_bar_style fade
986 The tab bar style, can be one of:
988 fade Each tab's edges fade into the background color. (See also
990 tab_fade)
991 slant Tabs look like the tabs in a physical file.
993 separator
995 Tabs are separated by a configurable separator. (See also
996 tab_separator)
997 powerline
999 Tabs are shown as a continuous line with "fancy" separators.
1000 (See also tab_powerline_style)
1001 custom A user-supplied Python function called draw_tab is loaded from
1003 the file tab_bar.py in the kitty config directory. For examples
1004 of how to write such a function, see the functions named
1005 draw_tab_with_* in kitty's source code: kitty/tab_bar.py. See
1006 also this discussion for examples from kitty users.
1007 hidden The tab bar is hidden. If you use this, you might want to create
1009 a mapping for the select_tab action which presents you with a
1010 list of tabs and allows for easy switching to a tab.
1011 tab_bar_align
1013 tab_bar_align left
1015 The horizontal alignment of the tab bar, can be one of: left, center,
1017 right.
1018 tab_bar_min_tabs
1020 tab_bar_min_tabs 2
1022 The minimum number of tabs that must exist before the tab bar is shown.
1024 tab_switch_strategy
1026 tab_switch_strategy previous
1028 The algorithm to use when switching to a tab when the current tab is
1030 closed. The default of previous will switch to the last used tab. A
1031 value of left will switch to the tab to the left of the closed tab. A
1032 value of right will switch to the tab to the right of the closed tab. A
1033 value of last will switch to the right-most tab.
1034 tab_fade
1036 tab_fade 0.25 0.5 0.75 1
1038 Control how each tab fades into the background when using fade for the
1040 tab_bar_style. Each number is an alpha (between zero and one) that con‐
1041 trols how much the corresponding cell fades into the background, with
1042 zero being no fade and one being full fade. You can change the number
1043 of cells used by adding/removing entries to this list.
1044 tab_separator
1046 tab_separator " ┇"
1048 The separator between tabs in the tab bar when using separator as the
1050 tab_bar_style.
1051 tab_powerline_style
1053 tab_powerline_style angled
1055 The powerline separator style between tabs in the tab bar when using
1057 powerline as the tab_bar_style, can be one of: angled, slanted, round.
1058 tab_activity_symbol
1060 tab_activity_symbol none
1062 Some text or a Unicode symbol to show on the tab if a window in the tab
1064 that does not have focus has some activity. If you want to use leading
1065 or trailing spaces, surround the text with quotes. See
1066 tab_title_template for how this is rendered.
1067 tab_title_template
1069 tab_title_template "{fmt.fg.red}{bell_symbol}{activity_symbol}{fmt.fg.tab}{title}"
1071 A template to render the tab title. The default just renders the title
1073 with optional symbols for bell and activity. If you wish to include the
1074 tab-index as well, use something like: {index}:{title}. Useful if you
1075 have shortcuts mapped for goto_tab N. If you prefer to see the index as
1076 a superscript, use {sup.index}. All data available is:
1077 title The current tab title.
1079 index The tab index useable with goto_tab N shortcuts.
1081 layout_name
1083 The current layout name.
1084 num_windows
1086 The number of windows in the tab.
1087 num_window_groups
1089 The number of window groups (not counting overlay windows) in
1090 the tab.
1091 tab.active_wd
1093 The working directory of the currently active window in the tab
1094 (expensive, requires syscall).
1095 max_title_length
1097 The maximum title length available.
1098 Note that formatting is done by Python's string formatting machinery,
1100 so you can use, for instance, {layout_name[:2].upper()} to show only
1101 the first two letters of the layout name, upper-cased. If you want to
1102 style the text, you can use styling directives, for example:
1103 {fmt.fg.red}red{fmt.fg.tab}normal{fmt.bg._00FF00}greenbg{fmt.bg.tab}.
1104 Similarly, for bold and italic: {fmt.bold}bold{fmt.nobold}nor‐
1105 mal{fmt.italic}italic{fmt.noitalic}. Note that for backward compati‐
1106 bility, if {bell_symbol} or {activity_symbol} are not present in the
1107 template, they are prepended to it.
1108 active_tab_title_template
1110 active_tab_title_template none
1112 Template to use for active tabs. If not specified falls back to
1114 tab_title_template.
1115 active_tab_foreground, active_tab_background, active_tab_font_style,
1117 inactive_tab_foreground, inactive_tab_background, inac‐
1118 tive_tab_font_style
1119 active_tab_foreground #000
1121 active_tab_background #eee
1122 active_tab_font_style bold-italic
1123 inactive_tab_foreground #444
1124 inactive_tab_background #999
1125 inactive_tab_font_style normal
1126 Tab bar colors and styles.
1128 tab_bar_background
1130 tab_bar_background none
1132 Background color for the tab bar. Defaults to using the terminal back‐
1134 ground color.
1135 tab_bar_margin_color
1137 tab_bar_margin_color none
1139 Color for the tab bar margin area. Defaults to using the terminal back‐
1141 ground color.
1142 foreground, background
1144 foreground #dddddd
1146 background #000000
1147 The foreground and background colors.
1149 background_opacity
1151 background_opacity 1.0
1153 The opacity of the background. A number between zero and one, where one
1155 is opaque and zero is fully transparent. This will only work if sup‐
1156 ported by the OS (for instance, when using a compositor under X11).
1157 Note that it only sets the background color's opacity in cells that
1158 have the same background color as the default terminal background, so
1159 that things like the status bar in vim, powerline prompts, etc. still
1160 look good. But it means that if you use a color theme with a background
1161 color in your editor, it will not be rendered as transparent. Instead
1162 you should change the default background color in your kitty config and
1163 not use a background color in the editor color scheme. Or use the es‐
1164 cape codes to set the terminals default colors in a shell script to
1165 launch your editor. Be aware that using a value less than 1.0 is a
1166 (possibly significant) performance hit. If you want to dynamically
1167 change transparency of windows, set dynamic_background_opacity to yes
1168 (this is off by default as it has a performance cost). Changing this
1169 option when reloading the config will only work if
1170 dynamic_background_opacity was enabled in the original config.
1171 background_image
1173 background_image none
1175 Path to a background image. Must be in PNG format.
1177 background_image_layout
1179 background_image_layout tiled
1181 Whether to tile, scale or clamp the background image. The value can be
1183 one of tiled, mirror-tiled, scaled, clamped or centered.
1184 background_image_linear
1186 background_image_linear no
1188 When background image is scaled, whether linear interpolation should be
1190 used.
1191 dynamic_background_opacity
1193 dynamic_background_opacity no
1195 Allow changing of the background_opacity dynamically, using either key‐
1197 board shortcuts (ctrl+shift+a>m and ctrl+shift+a>l) or the remote con‐
1198 trol facility. Changing this option by reloading the config is not sup‐
1199 ported.
1200 background_tint
1202 background_tint 0.0
1204 How much to tint the background image by the background color. This
1206 option makes it easier to read the text. Tinting is done using the cur‐
1207 rent background color for each window. This option applies only if
1208 background_opacity is set and transparent windows are supported or
1209 background_image is set.
1210 dim_opacity
1212 dim_opacity 0.75
1214 How much to dim text that has the DIM/FAINT attribute set. One means no
1216 dimming and zero means fully dimmed (i.e. invisible).
1217 selection_foreground, selection_background
1219 selection_foreground #000000
1221 selection_background #fffacd
1222 The foreground and background colors for text selected with the mouse.
1224 Setting both of these to none will cause a "reverse video" effect for
1225 selections, where the selection will be the cell text color and the
1226 text will become the cell background color. Setting only selec‐
1227 tion_foreground to none will cause the foreground color to be used un‐
1228 changed. Note that these colors can be overridden by the program run‐
1229 ning in the terminal.
1230
1232 The 256 terminal colors. There are 8 basic colors, each color has a
1233 dull and bright version, for the first 16 colors. You can set the re‐
1234 maining 240 colors as color16 to color255.
1235 color0, color8
1237 color0 #000000
1239 color8 #767676
1240 black
1242 color1, color9
1244 color1 #cc0403
1246 color9 #f2201f
1247 red
1249 color2, color10
1251 color2 #19cb00
1253 color10 #23fd00
1254 green
1256 color3, color11
1258 color3 #cecb00
1260 color11 #fffd00
1261 yellow
1263 color4, color12
1265 color4 #0d73cc
1267 color12 #1a8fff
1268 blue
1270 color5, color13
1272 color5 #cb1ed1
1274 color13 #fd28ff
1275 magenta
1277 color6, color14
1279 color6 #0dcdcd
1281 color14 #14ffff
1282 cyan
1284 color7, color15
1286 color7 #dddddd
1288 color15 #ffffff
1289 white
1291 mark1_foreground
1293 mark1_foreground black
1295 Color for marks of type 1
1297 mark1_background
1299 mark1_background #98d3cb
1301 Color for marks of type 1 (light steel blue)
1303 mark2_foreground
1305 mark2_foreground black
1307 Color for marks of type 2
1309 mark2_background
1311 mark2_background #f2dcd3
1313 Color for marks of type 1 (beige)
1315 mark3_foreground
1317 mark3_foreground black
1319 Color for marks of type 3
1321 mark3_background
1323 mark3_background #f274bc
1325 Color for marks of type 3 (violet)
1327 shell
1329 shell .
1331 The shell program to execute. The default value of . means to use what‐
1333 ever shell is set as the default shell for the current user. Note that
1334 on macOS if you change this, you might need to add --login and --inter‐
1335 active to ensure that the shell starts in interactive mode and reads
1336 its startup rc files.
1337 editor
1339 editor .
1341 The terminal based text editor (such as vim or nano) to use when edit‐
1343 ing the kitty config file or similar tasks.
1344 The default value of . means to use the environment variables VISUAL
1346 and EDITOR in that order. If these variables aren't set, kitty will run
1347 your shell ($SHELL -l -i -c env) to see if your shell startup rc files
1348 set VISUAL or EDITOR. If that doesn't work, kitty will cycle through
1349 various known editors (vim, emacs, etc.) and take the first one that
1350 exists on your system.
1351 close_on_child_death
1353 close_on_child_death no
1355 Close the window when the child process (shell) exits. With the default
1357 value no, the terminal will remain open when the child exits as long as
1358 there are still processes outputting to the terminal (for example dis‐
1359 owned or backgrounded processes). When enabled with yes, the window
1360 will close as soon as the child process exits. Note that setting it to
1361 yes means that any background processes still using the terminal can
1362 fail silently because their stdout/stderr/stdin no longer work.
1363 remote_control_password
1365 remote_control_password
1367 Allow other programs to control kitty using passwords. This option can
1369 be specified multiple times to add multiple passwords. If no passwords
1370 are present kitty will ask the user for permission if a program tries
1371 to use remote control with a password. A password can also optionally
1372 be associated with a set of allowed remote control actions. For exam‐
1373 ple:
1374 remote_control_password "my passphrase" get-colors set-colors focus-window focus-tab
1376 Only the specified actions will be allowed when using this password.
1378 Glob patterns can be used too, for example:
1379 remote_control_password "my passphrase" set-tab-* resize-*
1381 To get a list of available actions, run:
1383 kitty @ --help
1385 A set of actions to be allowed when no password is sent can be speci‐
1387 fied by using an empty password, for example:
1388 remote_control_password "" *-colors
1390 Finally, the path to a python module can be specified that provides a
1392 function is_cmd_allowed that is used to check every remote control com‐
1393 mand. See Customizing authorization with your own program for details.
1394 For example:
1395 remote_control_password "my passphrase" my_rc_command_checker.py
1397 Relative paths are resolved from the kitty configuration directory.
1399 allow_remote_control
1401 allow_remote_control no
1403 Allow other programs to control kitty. If you turn this on, other pro‐
1405 grams can control all aspects of kitty, including sending text to kitty
1406 windows, opening new windows, closing windows, reading the content of
1407 windows, etc. Note that this even works over SSH connections. The de‐
1408 fault setting of no prevents any form of remote control. The meaning of
1409 the various values are:
1410 password
1412 Remote control requests received over both the TTY device and
1413 the socket are confirmed based on passwords, see
1414 remote_control_password.
1415 socket-only
1417 Remote control requests received over a socket are accepted un‐
1418 conditionally. Requests received over the TTY are denied. See
1419 listen_on.
1420 socket Remote control requests received over a socket are accepted un‐
1422 conditionally. Requests received over the TTY are confirmed
1423 based on password.
1424 no Remote control is completely disabled.
1426 yes Remote control requests are always accepted.
1428 listen_on
1430 listen_on none
1432 Listen to the specified UNIX socket for remote control connections.
1434 Note that this will apply to all kitty instances. It can be overridden
1435 by the kitty --listen-on command line option, which also supports lis‐
1436 tening on a TCP socket. This option accepts only UNIX sockets, such as
1437 unix:${TEMP}/mykitty or unix:@mykitty (on Linux). Environment variables
1438 are expanded and relative paths are resolved with respect to the tempo‐
1439 rary directory. If {kitty_pid} is present, then it is replaced by the
1440 PID of the kitty process, otherwise the PID of the kitty process is ap‐
1441 pended to the value, with a hyphen. See the help for kitty --listen-on
1442 for more details. Note that this will be ignored unless
1443 allow_remote_control is set to either: yes, socket or socket-only.
1444 Changing this option by reloading the config is not supported.
1445 env
1447 env
1449 Specify the environment variables to be set in all child processes. Us‐
1451 ing the name with an equal sign (e.g. env VAR=) will set it to the
1452 empty string. Specifying only the name (e.g. env VAR) will remove the
1453 variable from the child process' environment. Note that environment
1454 variables are expanded recursively, for example:
1455 env VAR1=a
1457 env VAR2=${HOME}/${VAR1}/b
1458 The value of VAR2 will be <path to home directory>/a/b.
1460 watcher
1462 watcher
1464 Path to python file which will be loaded for Watching launched windows.
1466 Can be specified more than once to load multiple watchers. The watchers
1467 will be added to every kitty window. Relative paths are resolved rela‐
1468 tive to the kitty config directory. Note that reloading the config will
1469 only affect windows created after the reload.
1470 exe_search_path
1472 exe_search_path
1474 Control where kitty finds the programs to run. The default search order
1476 is: First search the system wide PATH, then ~/.local/bin and ~/bin. If
1477 still not found, the PATH defined in the login shell after sourcing all
1478 its startup files is tried. Finally, if present, the PATH specified by
1479 the env option is tried.
1480 This option allows you to prepend, append, or remove paths from this
1482 search order. It can be specified multiple times for multiple paths. A
1483 simple path will be prepended to the search order. A path that starts
1484 with the + sign will be append to the search order, after ~/bin above.
1485 A path that starts with the - sign will be removed from the entire
1486 search order. For example:
1487 exe_search_path /some/prepended/path
1489 exe_search_path +/some/appended/path
1490 exe_search_path -/some/excluded/path
1491 update_check_interval
1493 update_check_interval 24
1495 The interval to periodically check if an update to kitty is available
1497 (in hours). If an update is found, a system notification is displayed
1498 informing you of the available update. The default is to check every 24
1499 hours, set to zero to disable. Update checking is only done by the of‐
1500 ficial binary builds. Distro packages or source builds do not do update
1501 checking. Changing this option by reloading the config is not sup‐
1502 ported.
1503 startup_session
1505 startup_session none
1507 Path to a session file to use for all kitty instances. Can be overrid‐
1509 den by using the kitty --session command line option for individual in‐
1510 stances. See Startup Sessions in the kitty documentation for details.
1511 Note that relative paths are interpreted with respect to the kitty con‐
1512 fig directory. Environment variables in the path are expanded. Chang‐
1513 ing this option by reloading the config is not supported.
1514 clipboard_control
1516 clipboard_control write-clipboard write-primary read-clipboard-ask read-primary-ask
1518 Allow programs running in kitty to read and write from the clipboard.
1520 You can control exactly which actions are allowed. The possible actions
1521 are: write-clipboard, read-clipboard, write-primary, read-primary,
1522 read-clipboard-ask, read-primary-ask. The default is to allow writing
1523 to the clipboard and primary selection and to ask for permission when a
1524 program tries to read from the clipboard. Note that disabling the read
1525 confirmation is a security risk as it means that any program, even the
1526 ones running on a remote server via SSH can read your clipboard. See
1527 also clipboard_max_size.
1528 clipboard_max_size
1530 clipboard_max_size 64
1532 The maximum size (in MB) of data from programs running in kitty that
1534 will be stored for writing to the system clipboard. A value of zero
1535 means no size limit is applied. See also clipboard_control.
1536 file_transfer_confirmation_bypass
1538 file_transfer_confirmation_bypass
1540 The password that can be supplied to the file transfer kitten to skip
1542 the transfer confirmation prompt. This should only be used when initi‐
1543 ating transfers from trusted computers, over trusted networks or en‐
1544 crypted transports, as it allows any programs running on the remote ma‐
1545 chine to read/write to the local filesystem, without permission.
1546 allow_hyperlinks
1548 allow_hyperlinks yes
1550 Process hyperlink escape sequences (OSC 8). If disabled OSC 8 escape
1552 sequences are ignored. Otherwise they become clickable links, that you
1553 can click with the mouse or by using the hints kitten. The special
1554 value of ask means that kitty will ask before opening the link when
1555 clicked.
1556 shell_integration
1558 shell_integration enabled
1560 Enable shell integration on supported shells. This enables features
1562 such as jumping to previous prompts, browsing the output of the previ‐
1563 ous command in a pager, etc. on supported shells. Set to disabled to
1564 turn off shell integration, completely. It is also possible to disable
1565 individual features, set to a space separated list of these values:
1566 no-rc, no-cursor, no-title, no-cwd, no-prompt-mark, no-complete. See
1567 Shell integration for details.
1568 allow_cloning
1570 allow_cloning ask
1572 Control whether programs running in the terminal can request new win‐
1574 dows to be created. The canonical example is clone-in-kitty. By de‐
1575 fault, kitty will ask for permission for each clone request. Allowing
1576 cloning unconditionally gives programs running in the terminal (includ‐
1577 ing over SSH) permission to execute arbitrary code, as the user who is
1578 running the terminal, on the computer that the terminal is running on.
1579 clone_source_strategies
1581 clone_source_strategies venv,conda,env_var,path
1583 Control what shell code is sourced when running clone-in-kitty in the
1585 newly cloned window. The supported strategies are:
1586 venv Source the file $VIRTUAL_ENV/bin/activate. This is used by the
1588 Python stdlib venv module and allows cloning venvs automati‐
1589 cally.
1590 conda Run conda activate $CONDA_DEFAULT_ENV. This supports the virtual
1592 environments created by conda.
1593 env_var
1595 Execute the contents of the environment variable
1596 KITTY_CLONE_SOURCE_CODE with eval.
1597 path Source the file pointed to by the environment variable
1599 KITTY_CLONE_SOURCE_PATH.
1600 This option must be a comma separated list of the above values. This
1602 only source the first valid one in the above order.
1603 term
1605 term xterm-kitty
1607 The value of the TERM environment variable to set. Changing this can
1609 break many terminal programs, only change it if you know what you are
1610 doing, not because you read some advice on "Stack Overflow" to change
1611 it. The TERM variable is used by various programs to get information
1612 about the capabilities and behavior of the terminal. If you change it,
1613 depending on what programs you run, and how different the terminal you
1614 are changing it to is, various things from key-presses, to colors, to
1615 various advanced features may not work. Changing this option by reload‐
1616 ing the config will only affect newly created windows.
1617 wayland_titlebar_color
1619 wayland_titlebar_color system
1621 The color of the kitty window's titlebar on Wayland systems with client
1623 side window decorations such as GNOME. A value of system means to use
1624 the default system color, a value of background means to use the back‐
1625 ground color of the currently active window and finally you can use an
1626 arbitrary color, such as #12af59 or red.
1627 macos_titlebar_color
1629 macos_titlebar_color system
1631 The color of the kitty window's titlebar on macOS. A value of system
1633 means to use the default system color, light or dark can also be used
1634 to set it explicitly. A value of background means to use the background
1635 color of the currently active window and finally you can use an arbi‐
1636 trary color, such as #12af59 or red. WARNING: This option works by us‐
1637 ing a hack when arbitrary color (or background) is configured, as there
1638 is no proper Cocoa API for it. It sets the background color of the en‐
1639 tire window and makes the titlebar transparent. As such it is incompat‐
1640 ible with background_opacity. If you want to use both, you are probably
1641 better off just hiding the titlebar with hide_window_decorations.
1642 macos_option_as_alt
1644 macos_option_as_alt no
1646 Use the Option key as an Alt key on macOS. With this set to no, kitty
1648 will use the macOS native Option+Key to enter Unicode character behav‐
1649 ior. This will break any Alt+Key keyboard shortcuts in your terminal
1650 programs, but you can use the macOS Unicode input technique. You can
1651 use the values: left, right or both to use only the left, right or both
1652 Option keys as Alt, instead. Note that kitty itself always treats Op‐
1653 tion the same as Alt. This means you cannot use this option to config‐
1654 ure different kitty shortcuts for Option+Key vs. Alt+Key. Also, any
1655 kitty shortcuts using Option/Alt+Key will take priority, so that any
1656 such key presses will not be passed to terminal programs running inside
1657 kitty. Changing this option by reloading the config is not supported.
1658 macos_hide_from_tasks
1660 macos_hide_from_tasks no
1662 Hide the kitty window from running tasks on macOS (⌘+Tab and the Dock).
1664 Changing this option by reloading the config is not supported.
1665 macos_quit_when_last_window_closed
1667 macos_quit_when_last_window_closed no
1669 Have kitty quit when all the top-level windows are closed on macOS. By
1671 default, kitty will stay running, even with no open windows, as is the
1672 expected behavior on macOS.
1673 macos_window_resizable
1675 macos_window_resizable yes
1677 Disable this if you want kitty top-level OS windows to not be resizable
1679 on macOS. Changing this option by reloading the config will only affect
1680 newly created OS windows.
1681 macos_thicken_font
1683 macos_thicken_font 0
1685 Draw an extra border around the font with the given width, to increase
1687 legibility at small font sizes on macOS. For example, a value of 0.75
1688 will result in rendering that looks similar to sub-pixel antialiasing
1689 at common font sizes.
1690 macos_traditional_fullscreen
1692 macos_traditional_fullscreen no
1694 Use the macOS traditional full-screen transition, that is faster, but
1696 less pretty.
1697 macos_show_window_title_in
1699 macos_show_window_title_in all
1701 Control where the window title is displayed on macOS. A value of window
1703 will show the title of the currently active window at the top of the
1704 macOS window. A value of menubar will show the title of the currently
1705 active window in the macOS global menu bar, making use of otherwise
1706 wasted space. A value of all will show the title in both places, and
1707 none hides the title. See macos_menubar_title_max_length for how to
1708 control the length of the title in the menu bar.
1709 macos_menubar_title_max_length
1711 macos_menubar_title_max_length 0
1713 The maximum number of characters from the window title to show in the
1715 macOS global menu bar. Values less than one means that there is no max‐
1716 imum limit.
1717 macos_custom_beam_cursor
1719 macos_custom_beam_cursor no
1721 Use a custom mouse cursor for macOS that is easier to see on both light
1723 and dark backgrounds. Nowadays, the default macOS cursor already comes
1724 with a white border. WARNING: this might make your mouse cursor invisi‐
1725 ble on dual GPU machines. Changing this option by reloading the config
1726 is not supported.
1727 macos_colorspace
1729 macos_colorspace srgb
1731 The colorspace in which to interpret terminal colors. The default of
1733 srgb will cause colors to match those seen in web browsers. The value
1734 of default will use whatever the native colorspace of the display is.
1735 The value of displayp3 will use Apple's special snowflake display P3
1736 color space, which will result in over saturated (brighter) colors with
1737 some color shift. Reloading configuration will change this value only
1738 for newly created OS windows.
1739 linux_display_server
1741 linux_display_server auto
1743 Choose between Wayland and X11 backends. By default, an appropriate
1745 backend based on the system state is chosen automatically. Set it to
1746 x11 or wayland to force the choice. Changing this option by reloading
1747 the config is not supported.
1748 Keys are identified simply by their lowercase Unicode characters. For
1750 example: a for the A key, [ for the left square bracket key, etc. For
1751 functional keys, such as Enter or Escape, the names are present at
1752 Functional key definitions. For modifier keys, the names are ctrl (con‐
1753 trol, ⌃), shift (⇧), alt (opt, option, ⌥), super (cmd, command, ⌘).
1754 See also: GLFW mods
1755 On Linux you can also use XKB key names to bind keys that are not sup‐
1757 ported by GLFW. See XKB keys for a list of key names. The name to use
1758 is the part after the XKB_KEY_ prefix. Note that you can only use an
1759 XKB key name for keys that are not known as GLFW keys.
1760 Finally, you can use raw system key codes to map keys, again only for
1762 keys that are not known as GLFW keys. To see the system key code for a
1763 key, start kitty with the kitty --debug-input option, kitty will output
1764 some debug text for every key event. In that text look for native_code,
1765 the value of that becomes the key name in the shortcut. For example:
1766 on_key_input: glfw key: 0x61 native_code: 0x61 action: PRESS mods: none text: 'a'
1768 Here, the key name for the A key is 0x61 and you can use it with:
1770 map ctrl+0x61 something
1772 to map Ctrl+A to something.
1774 You can use the special action no_op to unmap a keyboard shortcut that
1776 is assigned in the default configuration:
1777 map kitty_mod+space no_op
1779 If you would like kitty to completely ignore a key event, not even
1781 sending it to the program running in the terminal, map it to
1782 discard_event:
1783 map kitty_mod+f1 discard_event
1785 You can combine multiple actions to be triggered by a single shortcut
1787 with combine action, using the syntax below:
1788 map key combine <separator> action1 <separator> action2 <separator> action3 ...
1790 For example:
1792 map kitty_mod+e combine : new_window : next_layout
1794 This will create a new window and switch to the next available layout.
1796 You can use multi-key shortcuts with the syntax shown below:
1798 map key1>key2>key3 action
1800 For example:
1802 map ctrl+f>2 set_font_size 20
1804 The full list of actions that can be mapped to key presses is available
1806 here.
1807 kitty_mod
1809 kitty_mod ctrl+shift
1811 Special modifier key alias for default shortcuts. You can change the
1813 value of this option to alter all default shortcuts that use kitty_mod.
1814 clear_all_shortcuts
1816 clear_all_shortcuts no
1818 Remove all shortcut definitions up to this point. Useful, for instance,
1820 to remove the default shortcuts.
1821 action_alias
1823 action_alias launch_tab launch --type=tab --cwd=current
1825 Define action aliases to avoid repeating the same options in multiple
1827 mappings. Aliases can be defined for any action and will be expanded
1828 recursively. For example, the above alias allows you to create mappings
1829 to launch a new tab in the current working directory without duplica‐
1830 tion:
1831 map f1 launch_tab vim
1833 map f2 launch_tab emacs
1834 Similarly, to alias kitten invocation:
1836 action_alias hints kitten hints --hints-offset=0
1838 kitten_alias
1840 kitten_alias hints hints --hints-offset=0
1842 Like action_alias above, but specifically for kittens. Generally, pre‐
1844 fer to use action_alias. This option is a legacy version, present for
1845 backwards compatibility. It causes all invocations of the aliased kit‐
1846 ten to be substituted. So the example above will cause all invocations
1847 of the hints kitten to have the --hints-offset=0 option applied.
1848
1850 Copy to clipboard
1851 map ctrl+shift+c copy_to_clipboard
1853 map cmd+c copy_to_clipboard 🍎
1854 There is also a copy_or_interrupt action that can be optionally mapped
1856 to Ctrl+C. It will copy only if there is a selection and send an inter‐
1857 rupt otherwise. Similarly, copy_and_clear_or_interrupt will copy and
1858 clear the selection or send an interrupt if there is no selection.
1859 Paste from clipboard
1861 map ctrl+shift+v paste_from_clipboard
1863 map cmd+v paste_from_clipboard 🍎
1864 Paste from selection
1866 map ctrl+shift+s paste_from_selection
1868 map shift+insert paste_from_selection
1869 Pass selection to program
1871 map ctrl+shift+o pass_selection_to_program
1873 You can also pass the contents of the current selection to any program
1875 with pass_selection_to_program. By default, the system's open program
1876 is used, but you can specify your own, the selection will be passed as
1877 a command line argument to the program. For example:
1878 map kitty_mod+o pass_selection_to_program firefox
1880 You can pass the current selection to a terminal program running in a
1882 new kitty window, by using the @selection placeholder:
1883 map kitty_mod+y new_window less @selection
1885
1887 Scroll line up
1888 map ctrl+shift+up scroll_line_up
1890 map ctrl+shift+k scroll_line_up
1891 map opt+cmd+page_up scroll_line_up 🍎
1892 map cmd+up scroll_line_up 🍎
1893 Scroll line down
1895 map ctrl+shift+down scroll_line_down
1897 map ctrl+shift+j scroll_line_down
1898 map opt+cmd+page_down scroll_line_down 🍎
1899 map cmd+down scroll_line_down 🍎
1900 Scroll page up
1902 map ctrl+shift+page_up scroll_page_up
1904 map cmd+page_up scroll_page_up 🍎
1905 Scroll page down
1907 map ctrl+shift+page_down scroll_page_down
1909 map cmd+page_down scroll_page_down 🍎
1910 Scroll to top
1912 map ctrl+shift+home scroll_home
1914 map cmd+home scroll_home 🍎
1915 Scroll to bottom
1917 map ctrl+shift+end scroll_end
1919 map cmd+end scroll_end 🍎
1920 Scroll to previous shell prompt
1922 map ctrl+shift+z scroll_to_prompt -1
1924 Use a parameter of 0 for scroll_to_prompt to scroll to the last jumped
1926 to or the last clicked position. Requires shell integration to work.
1927 Scroll to next shell prompt
1929 map ctrl+shift+x scroll_to_prompt 1
1931 Browse scrollback buffer in pager
1933 map ctrl+shift+h show_scrollback
1935 You can pipe the contents of the current screen and history buffer as
1937 STDIN to an arbitrary program using launch --stdin-source. For exam‐
1938 ple, the following opens the scrollback buffer in less in an overlay
1939 window:
1940 map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting --type=overlay less +G -R
1942 For more details on piping screen and buffer contents to external pro‐
1944 grams, see The launch command.
1945 Browse output of the last shell command in pager
1947 map ctrl+shift+g show_last_command_output
1949 You can also define additional shortcuts to get the command output.
1951 For example, to get the first command output on screen:
1952 map f1 show_first_command_output_on_screen
1954 To get the command output that was last accessed by a keyboard action
1956 or mouse action:
1957 map f1 show_last_visited_command_output
1959 You can pipe the output of the last command run in the shell using the
1961 launch action. For example, the following opens the output in less in
1962 an overlay window:
1963 map f1 launch --stdin-source=@last_cmd_output --stdin-add-formatting --type=overlay less +G -R
1965 To get the output of the first command on the screen, use
1967 @first_cmd_output_on_screen. To get the output of the last jumped to
1968 command, use @last_visited_cmd_output.
1969 Requires shell integration to work.
1971
1973 New window
1974 map ctrl+shift+enter new_window
1976 map cmd+enter new_window 🍎
1977 You can open a new kitty window running an arbitrary program, for exam‐
1979 ple:
1980 map kitty_mod+y launch mutt
1982 You can open a new window with the current working directory set to the
1984 working directory of the current window using:
1985 map ctrl+alt+enter launch --cwd=current
1987 You can open a new window that is allowed to control kitty via the
1989 kitty remote control facility with launch --allow-remote-control. Any
1990 programs running in that window will be allowed to control kitty. For
1991 example:
1992 map ctrl+enter launch --allow-remote-control some_program
1994 You can open a new window next to the currently active window or as the
1996 first window, with:
1997 map ctrl+n launch --location=neighbor
1999 map ctrl+f launch --location=first
2000 For more details, see The launch command.
2002 New OS window
2004 map ctrl+shift+n new_os_window
2006 map cmd+n new_os_window 🍎
2007 Works like new_window above, except that it opens a top-level OS win‐
2009 dow. In particular you can use new_os_window_with_cwd to open a window
2010 with the current working directory.
2011 Close window
2013 map ctrl+shift+w close_window
2015 map shift+cmd+d close_window 🍎
2016 Next window
2018 map ctrl+shift+] next_window
2020 Previous window
2022 map ctrl+shift+[ previous_window
2024 Move window forward
2026 map ctrl+shift+f move_window_forward
2028 Move window backward
2030 map ctrl+shift+b move_window_backward
2032 Move window to top
2034 map ctrl+shift+` move_window_to_top
2036 Start resizing window
2038 map ctrl+shift+r start_resizing_window
2040 map cmd+r start_resizing_window 🍎
2041 First window
2043 map ctrl+shift+1 first_window
2045 map cmd+1 first_window 🍎
2046 Second window
2048 map ctrl+shift+2 second_window
2050 map cmd+2 second_window 🍎
2051 Third window
2053 map ctrl+shift+3 third_window
2055 map cmd+3 third_window 🍎
2056 Fourth window
2058 map ctrl+shift+4 fourth_window
2060 map cmd+4 fourth_window 🍎
2061 Fifth window
2063 map ctrl+shift+5 fifth_window
2065 map cmd+5 fifth_window 🍎
2066 Sixth window
2068 map ctrl+shift+6 sixth_window
2070 map cmd+6 sixth_window 🍎
2071 Seventh window
2073 map ctrl+shift+7 seventh_window
2075 map cmd+7 seventh_window 🍎
2076 Eight window
2078 map ctrl+shift+8 eighth_window
2080 map cmd+8 eighth_window 🍎
2081 Ninth window
2083 map ctrl+shift+9 ninth_window
2085 map cmd+9 ninth_window 🍎
2086 Tenth window
2088 map ctrl+shift+0 tenth_window
2090 Visually select and focus window
2092 map ctrl+shift+f7 focus_visible_window
2094 Display overlay numbers and alphabets on the window, and switch the fo‐
2096 cus to the window when you press the key. When there are only two win‐
2097 dows, the focus will be switched directly without displaying the over‐
2098 lay. You can change the overlay characters and their order with option
2099 visual_window_select_characters.
2100 Visually swap window with another
2102 map ctrl+shift+f8 swap_with_window
2104 Works like focus_visible_window above, but swaps the window.
2106
2108 Next tab
2109 map ctrl+shift+right next_tab
2111 map shift+cmd+] next_tab 🍎
2112 map ctrl+tab next_tab
2113 Previous tab
2115 map ctrl+shift+left previous_tab
2117 map shift+cmd+[ previous_tab 🍎
2118 map ctrl+shift+tab previous_tab
2119 New tab
2121 map ctrl+shift+t new_tab
2123 map cmd+t new_tab 🍎
2124 Close tab
2126 map ctrl+shift+q close_tab
2128 map cmd+w close_tab 🍎
2129 Close OS window
2131 map shift+cmd+w close_os_window 🍎
2133 Move tab forward
2135 map ctrl+shift+. move_tab_forward
2137 Move tab backward
2139 map ctrl+shift+, move_tab_backward
2141 Set tab title
2143 map ctrl+shift+alt+t set_tab_title
2145 map shift+cmd+i set_tab_title 🍎
2146 You can also create shortcuts to go to specific tabs, with 1 being the
2148 first tab, 2 the second tab and -1 being the previously active tab, and
2149 any number larger than the last tab being the last tab:
2150 map ctrl+alt+1 goto_tab 1
2152 map ctrl+alt+2 goto_tab 2
2153 Just as with new_window above, you can also pass the name of arbitrary
2155 commands to run when using new_tab and new_tab_with_cwd. Finally, if
2156 you want the new tab to open next to the current tab rather than at the
2157 end of the tabs list, use:
2158 map ctrl+t new_tab !neighbor [optional cmd to run]
2160
2162 Next layout
2163 map ctrl+shift+l next_layout
2165 You can also create shortcuts to switch to specific layouts:
2167 map ctrl+alt+t goto_layout tall
2169 map ctrl+alt+s goto_layout stack
2170 Similarly, to switch back to the previous layout:
2172 map ctrl+alt+p last_used_layout
2174 There is also a toggle_layout action that switches to the named layout
2176 or back to the previous layout if in the named layout. Useful to tempo‐
2177 rarily "zoom" the active window by switching to the stack layout:
2178 map ctrl+alt+z toggle_layout stack
2180
2182 You can change the font size for all top-level kitty OS windows at a
2183 time or only the current one.
2184 Increase font size
2186 map ctrl+shift+equal change_font_size all +2.0
2188 map ctrl+shift+plus change_font_size all +2.0
2189 map ctrl+shift+kp_add change_font_size all +2.0
2190 map cmd+plus change_font_size all +2.0 🍎
2191 map cmd+equal change_font_size all +2.0 🍎
2192 map shift+cmd+equal change_font_size all +2.0 🍎
2193 Decrease font size
2195 map ctrl+shift+minus change_font_size all -2.0
2197 map ctrl+shift+kp_subtract change_font_size all -2.0
2198 map cmd+minus change_font_size all -2.0 🍎
2199 map shift+cmd+minus change_font_size all -2.0 🍎
2200 Reset font size
2202 map ctrl+shift+backspace change_font_size all 0
2204 map cmd+0 change_font_size all 0 🍎
2205 To setup shortcuts for specific font sizes:
2207 map kitty_mod+f6 change_font_size all 10.0
2209 To setup shortcuts to change only the current OS window's font size:
2211 map kitty_mod+f6 change_font_size current 10.0
2213
2215 Use the hints kitten to select text and either pass it to an external
2216 program or insert it into the terminal or copy it to the clipboard.
2217 Open URL
2219 map ctrl+shift+e open_url_with_hints
2221 Open a currently visible URL using the keyboard. The program used to
2223 open the URL is specified in open_url_with.
2224 Insert selected path
2226 map ctrl+shift+p>f kitten hints --type path --program -
2228 Select a path/filename and insert it into the terminal. Useful, for in‐
2230 stance to run git commands on a filename output from a previous git
2231 command.
2232 Open selected path
2234 map ctrl+shift+p>shift+f kitten hints --type path
2236 Select a path/filename and open it with the default open program.
2238 Insert selected line
2240 map ctrl+shift+p>l kitten hints --type line --program -
2242 Select a line of text and insert it into the terminal. Useful for the
2244 output of things like: ls -1.
2245 Insert selected word
2247 map ctrl+shift+p>w kitten hints --type word --program -
2249 Select words and insert into terminal.
2251 Insert selected hash
2253 map ctrl+shift+p>h kitten hints --type hash --program -
2255 Select something that looks like a hash and insert it into the termi‐
2257 nal. Useful with git, which uses SHA1 hashes to identify commits.
2258 Open the selected file at the selected line
2260 map ctrl+shift+p>n kitten hints --type linenum
2262 Select something that looks like filename:linenum and open it in vim at
2264 the specified line number.
2265 Open the selected hyperlink
2267 map ctrl+shift+p>y kitten hints --type hyperlink
2269 Select a hyperlink (i.e. a URL that has been marked as such by the ter‐
2271 minal program, for example, by ls --hyperlink=auto).
2272 The hints kitten has many more modes of operation that you can map to
2274 different shortcuts. For a full description see hints kitten.
2275
2277 Show documentation
2278 map ctrl+shift+f1 show_kitty_doc overview
2280 Toggle fullscreen
2282 map ctrl+shift+f11 toggle_fullscreen
2284 map ctrl+cmd+f toggle_fullscreen 🍎
2285 Toggle maximized
2287 map ctrl+shift+f10 toggle_maximized
2289 Toggle macOS secure keyboard entry
2291 map opt+cmd+s toggle_macos_secure_keyboard_entry 🍎
2293 Unicode input
2295 map ctrl+shift+u kitten unicode_input
2297 map ctrl+cmd+space kitten unicode_input 🍎
2298 Edit config file
2300 map ctrl+shift+f2 edit_config_file
2302 map cmd+, edit_config_file 🍎
2303 Open the kitty command shell
2305 map ctrl+shift+escape kitty_shell window
2307 Open the kitty shell in a new window / tab / overlay / os_window to
2309 control kitty using commands.
2310 Increase background opacity
2312 map ctrl+shift+a>m set_background_opacity +0.1
2314 Decrease background opacity
2316 map ctrl+shift+a>l set_background_opacity -0.1
2318 Make background fully opaque
2320 map ctrl+shift+a>1 set_background_opacity 1
2322 Reset background opacity
2324 map ctrl+shift+a>d set_background_opacity default
2326 Reset the terminal
2328 map ctrl+shift+delete clear_terminal reset active
2330 map opt+cmd+r clear_terminal reset active 🍎
2331 You can create shortcuts to clear/reset the terminal. For example:
2333 # Reset the terminal
2335 map f1 clear_terminal reset active
2336 # Clear the terminal screen by erasing all contents
2337 map f1 clear_terminal clear active
2338 # Clear the terminal scrollback by erasing it
2339 map f1 clear_terminal scrollback active
2340 # Scroll the contents of the screen into the scrollback
2341 map f1 clear_terminal scroll active
2342 # Clear everything up to the line with the cursor
2343 map f1 clear_terminal to_cursor active
2344 If you want to operate on all kitty windows instead of just the current
2346 one, use all instead of active.
2347 It is also possible to remap Ctrl+L to both scroll the current screen
2349 contents into the scrollback buffer and clear the screen, instead of
2350 just clearing the screen, for example, for ZSH add the following to
2351 ~/.zshrc:
2352 scroll-and-clear-screen() {
2354 printf '\n%.0s' {1..$LINES}
2355 zle clear-screen
2356 }
2357 zle -N scroll-and-clear-screen
2358 bindkey '^l' scroll-and-clear-screen
2359 Clear up to cursor line
2361 map cmd+k clear_terminal to_cursor active 🍎
2363 Reload kitty.conf
2365 map ctrl+shift+f5 load_config_file
2367 map ctrl+cmd+, load_config_file 🍎
2368 Reload kitty.conf, applying any changes since the last time it was
2370 loaded. Note that a handful of options cannot be dynamically changed
2371 and require a full restart of kitty. Particularly, when changing short‐
2372 cuts for actions located on the macOS global menu bar, a full restart
2373 is needed. You can also map a keybinding to load a different config
2374 file, for example:
2375 map f5 load_config /path/to/alternative/kitty.conf
2377 Note that all options from the original kitty.conf are discarded, in
2379 other words the new configuration replace the old ones.
2380 Debug kitty configuration
2382 map ctrl+shift+f6 debug_config
2384 map opt+cmd+, debug_config 🍎
2385 Show details about exactly what configuration kitty is running with and
2387 its host environment. Useful for debugging issues.
2388 Send arbitrary text on key presses
2390 You can tell kitty to send arbitrary (UTF-8) encoded text to the client
2392 program when pressing specified shortcut keys. For example:
2393 map ctrl+alt+a send_text all Special text
2395 This will send "Special text" when you press the Ctrl+Alt+A key combi‐
2397 nation. The text to be sent is a python string literal so you can use
2398 escapes like x1b to send control codes or u21fb to send Unicode charac‐
2399 ters (or you can just input the Unicode characters directly as UTF-8
2400 text). You can use kitty +kitten show_key to get the key escape codes
2401 you want to emulate.
2402 The first argument to send_text is the keyboard modes in which to acti‐
2404 vate the shortcut. The possible values are normal, application, kitty
2405 or a comma separated combination of them. The modes normal and appli‐
2406 cation refer to the DECCKM cursor key mode for terminals, and kitty
2407 refers to the kitty extended keyboard protocol. The special value all
2408 means all of them.
2409 Some more examples:
2411 # Output a word and move the cursor to the start of the line (like typing and pressing Home)
2413 map ctrl+alt+a send_text normal Word\x1b[H
2414 map ctrl+alt+a send_text application Word\x1bOH
2415 # Run a command at a shell prompt (like typing the command and pressing Enter)
2416 map ctrl+alt+a send_text normal,application some command with arguments\r
2417 Open kitty Website
2419 map shift+cmd+/ open_url https://sw.kovidgoyal.net/kitty/ 🍎
2421 You can edit a fully commented sample kitty.conf by pressing the
2423 ctrl+shift+f2 shortcut in kitty. This will generate a config file with
2424 full documentation and all settings commented out. If you have a
2425 pre-existing kitty.conf, then that will be used instead, delete it to
2426 see the sample file.
2427 See the list of all the things you can make kitty can do.
2429
2431 The actions described below can be mapped to any key press or mouse ac‐
2432 tion using the map and mouse_map directives in kitty.conf. For configu‐
2433 ration examples, see the default shortcut links for each action.
2434
2436 clear_selection
2437 Clear the current selection
2439 copy_and_clear_or_interrupt
2441 Copy the selected text from the active window to the clipboard and
2443 clear selection, if no selection, send SIGINT (aka ctrl+c)
2444 copy_ansi_to_clipboard
2446 Copy the selected text from the active window to the clipboard with
2448 ANSI formatting codes
2449 copy_or_interrupt
2451 Copy the selected text from the active window to the clipboard, if no
2453 selection, send SIGINT (aka ctrl+c)
2454 copy_to_clipboard
2456 Copy the selected text from the active window to the clipboard
2458 Default shortcuts using this action: ctrl+shift+c
2460 pass_selection_to_program
2462 Pass the selected text from the active window to the specified program
2464 Default shortcuts using this action: ctrl+shift+o
2466 paste
2468 Paste the specified text into the current window
2470 show_first_command_output_on_screen
2472 Show output from the first shell command on screen in a pager like less
2474 Requires Shell integration to work
2476 show_last_command_output
2478 Show output from the last shell command in a pager like less
2480 Requires Shell integration to work
2482 Default shortcuts using this action: ctrl+shift+g
2484 show_last_non_empty_command_output
2486 Show the last non-empty output from a shell command in a pager like
2488 less
2489 Requires Shell integration to work
2491 show_last_visited_command_output
2493 Show the first command output below the last scrolled position via
2495 scroll_to_prompt
2496 or the last mouse clicked command output in a pager like less
2498 Requires Shell integration to work
2500 show_scrollback
2502 Show scrollback in a pager like less
2504 Default shortcuts using this action: ctrl+shift+h
2506 copy_to_buffer
2508 Copy the selection from the active window to the specified buffer
2510 See Multiple copy/paste buffers for details.
2512 paste_from_buffer
2514 Paste from the specified buffer to the active window
2516 See Multiple copy/paste buffers for details.
2518 paste_from_clipboard
2520 Paste from the clipboard to the active window
2522 Default shortcuts using this action: ctrl+shift+v
2524 paste_from_selection
2526 Paste from the primary selection, if present, otherwise the clipboard
2528 to the active window
2529 Default shortcuts using this action: ctrl+shift+s
2531
2533 dump_lines_with_attrs
2534 Show a dump of the current lines in the scrollback + screen with their
2536 line attributes
2537 close_shared_ssh_connections
2539 Close all shared SSH connections
2541 See share_connections for details.
2543 debug_config
2545 Show the effective configuration kitty is running with
2547 Default shortcuts using this action: ctrl+shift+f6
2549 show_kitty_env_vars
2551 Show the environment variables that the kitty process sees
2553
2555 goto_layout
2556 Switch to the named layout
2558 For example:
2560 map f1 goto_layout tall
2562 last_used_layout
2564 Go to the previously used layout
2566 layout_action
2568 Perform a layout specific action. See Arrange windows for details
2570 next_layout
2572 Go to the next enabled layout
2574 Default shortcuts using this action: ctrl+shift+l
2576 toggle_layout
2578 Toggle the named layout
2580 Switches to the named layout if another layout is current, otherwise
2582 switches to the last used layout. Useful to "zoom" a window temporarily
2583 by switching to the stack layout. For example:
2584 map f1 toggle_layout stack
2586
2588 remove_marker
2589 Remove a previously created marker
2591 scroll_to_mark
2593 Scroll to the next or previous mark of the specified type
2595 toggle_marker
2597 Toggle the current marker on/off
2599 create_marker
2601 Create a new marker
2603
2605 send_text
2606 Send the specified text to the active window
2608 See send_text for details.
2610 Default shortcuts using this action: ctrl+shift+alt+h
2612 show_kitty_doc
2614 Display the specified kitty documentation, preferring a local copy, if
2616 found.
2617 For example:
2619 # show the config docs
2621 map f1 show_kitty_doc conf
2622 # show the ssh kitten docs
2623 map f1 show_kitty_doc kittens/ssh
2624 Default shortcuts using this action: ctrl+shift+f1
2626 signal_child
2628 Send the specified SIGNAL to the foreground process in the active win‐
2630 dow
2631 For example:
2633 map f1 signal_child SIGTERM
2635 clear_terminal
2637 Clear the terminal
2639 See reset_terminal for details. For example:
2641 # Reset the terminal
2643 map f1 clear_terminal reset active
2644 # Clear the terminal screen by erasing all contents
2645 map f1 clear_terminal clear active
2646 # Clear the terminal scrollback by erasing it
2647 map f1 clear_terminal scrollback active
2648 # Scroll the contents of the screen into the scrollback
2649 map f1 clear_terminal scroll active
2650 # Clear everything up to the line with the cursor
2651 map f1 clear_terminal to_cursor active
2652 Default shortcuts using this action: cmd+k, ctrl+shift+delete
2654 combine
2656 Combine multiple actions and map to a single keypress
2658 The syntax is:
2660 map key combine <separator> action1 <separator> action2 <separator> action3 ...
2662 For example:
2664 map kitty_mod+e combine : new_window : next_layout
2666 disable_ligatures_in
2668 Turn on/off ligatures in the specified window
2670 See disable_ligatures for details
2672 discard_event
2674 Discard this event completely ignoring it
2676 edit_config_file
2678 Edit the kitty.conf config file in your favorite text editor
2680 Default shortcuts using this action: ctrl+shift+f2
2682 input_unicode_character
2684 Input an arbitrary unicode character. See Unicode input for details.
2686 kitten
2688 Run the specified kitten. See Custom kittens for details
2690 Default shortcuts using this action:
2692 • Hints - ctrl+shift+p>h Insert selected hash
2694 • Hints - ctrl+shift+p>l Insert selected line
2696 • Hints - ctrl+shift+p>f Insert selected path
2698 • Hints - ctrl+shift+p>w Insert selected word
2700 • Hints - ctrl+shift+p>shift+f Open selected path
2702 • Hints - ctrl+shift+p>n Open the selected file at the selected line
2704 • Hints - ctrl+shift+p>y Open the selected hyperlink
2706 • Unicode input - ctrl+shift+u Unicode input
2708 kitty_shell
2710 Run the kitty shell to control kitty with commands
2712 Default shortcuts using this action: ctrl+shift+escape
2714 launch
2716 Launch the specified program in a new window/tab/etc.
2718 See The launch command for details
2720 load_config_file
2722 Reload the config file
2724 If mapped without arguments reloads the default config file, otherwise
2726 loads the specified config files, in order. Loading a config file re‐
2727 places all config options. For example:
2728 map f5 load_config_file /path/to/some/kitty.conf
2730 Default shortcuts using this action: ctrl+shift+f5
2732 open_url
2734 Open the specified URL
2736 Default shortcuts using this action: shift+cmd+/
2738 open_url_with_hints
2740 Click a URL using the keyboard
2742 Default shortcuts using this action: ctrl+shift+e
2744 remote_control
2746 Run a remote control command
2748 For example:
2750 map f1 remote_control set-spacing margin=30
2752 See Mapping key presses to remote control commands for details.
2754 set_colors
2756 Change colors in the specified windows
2758 For details, see kitty @ set-colors. For example:
2760 map f5 set_colors --configured /path/to/some/config/file/colors.conf
2762 toggle_macos_secure_keyboard_entry
2764 Toggle macOS secure keyboard entry
2766 Default shortcuts using this action: opt+cmd+s
2768 no_op
2770 Unbind a shortcut
2772 Mapping a shortcut to no_op causes kitty to not intercept the key
2774 stroke anymore, instead passing it to the program running inside it.
2775
2777 mouse_click_url
2778 Click the URL under the mouse
2780 mouse_click_url_or_select
2782 Click the URL under the mouse only if the screen has no selection
2784 mouse_handle_click
2786 Handle a mouse click
2788 Try to perform the specified actions one after the other till one of
2790 them is successful. Supported actions are:
2791 selection - check for a selection and if one exists abort processing
2793 link - if a link exists under the mouse, click it
2794 prompt - if the mouse click happens at a shell prompt move the cursor to the mouse location
2795 For examples, see Mouse actions
2797 mouse_select_command_output
2799 Select clicked command output
2801 Requires Shell integration to work
2803 mouse_selection
2805 Manipulate the selection based on the current mouse position
2807 For examples, see Mouse actions
2809 mouse_show_command_output
2811 Show clicked command output in a pager like less
2813 Requires Shell integration to work
2815 paste_selection
2817 Paste the current primary selection
2819 paste_selection_or_clipboard
2821 Paste the current primary selection or the clipboard if no selection is
2823 present
2824
2826 scroll_end
2827 Scroll to the bottom of the scrollback buffer
2829 Default shortcuts using this action: ctrl+shift+end
2831 scroll_home
2833 Scroll to the top of the scrollback buffer
2835 Default shortcuts using this action: ctrl+shift+home
2837 scroll_line_down
2839 Scroll down by one line
2841 Default shortcuts using this action: ctrl+shift+down
2843 scroll_line_up
2845 Scroll up by one line
2847 Default shortcuts using this action: ctrl+shift+up
2849 scroll_page_down
2851 Scroll down by one page
2853 Default shortcuts using this action: ctrl+shift+page_down
2855 scroll_page_up
2857 Scroll up by one page
2859 Default shortcuts using this action: ctrl+shift+page_up
2861 scroll_prompt_to_bottom
2863 Scroll prompt to the bottom of the screen, filling in extra lines from
2865 the scrollback buffer
2866 scroll_prompt_to_top
2868 Scroll prompt to the top of the screen, filling screen with empty lines
2870 scroll_to_prompt
2872 Scroll to the previous/next shell command prompt
2874 Allows easy jumping from one command to the next. Requires working
2876 Shell integration. Takes a single, optional, number as argument which
2877 is the number of prompts to jump, negative values jump up and positive
2878 values jump down. A value of zero will jump to the last prompt visited
2879 by this action. For example:
2880 map ctrl+p scroll_to_prompt -1 # jump to previous
2882 map ctrl+n scroll_to_prompt 1 # jump to next
2883 map ctrl+o scroll_to_prompt 0 # jump to last visited
2884 Default shortcuts using this action: ctrl+shift+x, ctrl+shift+z
2886
2888 close_other_tabs_in_os_window
2889 Close all the tabs in the current OS window other than the currently
2891 active tab
2892 close_tab
2894 Close the current tab
2896 Default shortcuts using this action: ctrl+shift+q
2898 detach_tab
2900 Detach a tab, moving it to another OS Window
2902 See detaching windows for details.
2904 goto_tab
2906 Go to the specified tab, by number, starting with 1
2908 Zero and negative numbers go to previously active tabs
2910 move_tab_backward
2912 Move the active tab backward
2914 Default shortcuts using this action: ctrl+shift+,
2916 move_tab_forward
2918 Move the active tab forward
2920 Default shortcuts using this action: ctrl+shift+.
2922 new_tab
2924 Create a new tab
2926 Default shortcuts using this action: ctrl+shift+t
2928 new_tab_with_cwd
2930 Create a new tab with working directory for the window in it set to the
2932 same as the active window
2933 next_tab
2935 Make the next tab active
2937 Default shortcuts using this action: ctrl+shift+right
2939 previous_tab
2941 Make the previous tab active
2943 Default shortcuts using this action: ctrl+shift+left
2945 select_tab
2947 Interactively select a tab to switch to
2949 set_tab_title
2951 Change the title of the active tab interactively, by typing in the new
2953 title.
2954 If you specify an argument to this action then that is used as the ti‐
2956 tle instead of asking for it. Use the empty string ("") to reset the
2957 title to default. For example:
2958 # interactive usage
2960 map f1 set_tab_title
2961 # set a specific title
2962 map f2 set_tab_title some title
2963 # reset to default
2964 map f3 set_tab_title ""
2965 Default shortcuts using this action: ctrl+shift+alt+t
2967
2969 close_other_windows_in_tab
2970 Close all windows in the tab other than the currently active window
2972 eighth_window
2974 Focus the eighth window
2976 Default shortcuts using this action: ctrl+shift+8
2978 fifth_window
2980 Focus the fifth window
2982 Default shortcuts using this action: ctrl+shift+5
2984 first_window
2986 Focus the first window
2988 Default shortcuts using this action: ctrl+shift+1
2990 focus_visible_window
2992 Focus a visible window by pressing the number of the window. Window
2994 numbers are displayed
2995 over the windows for easy selection in this mode. See
2997 visual_window_select_characters.
2998 Default shortcuts using this action: ctrl+shift+f7
3000 fourth_window
3002 Focus the fourth window
3004 Default shortcuts using this action: ctrl+shift+4
3006 move_window
3008 Move the window in the specified direction
3010 For example:
3012 map ctrl+left move_window left
3014 map ctrl+down move_window bottom
3015 move_window_backward
3017 Move active window backward (swap it with the previous window)
3019 Default shortcuts using this action: ctrl+shift+b
3021 move_window_forward
3023 Move active window forward (swap it with the next window)
3025 Default shortcuts using this action: ctrl+shift+f
3027 move_window_to_top
3029 Move active window to the top (make it the first window)
3031 Default shortcuts using this action: ctrl+shift+`
3033 neighboring_window
3035 Focus the neighboring window in the current tab
3037 For example:
3039 map ctrl+left neighboring_window left
3041 map ctrl+down neighboring_window bottom
3042 next_window
3044 Focus the next window in the current tab
3046 Default shortcuts using this action: ctrl+shift+]
3048 ninth_window
3050 Focus the ninth window
3052 Default shortcuts using this action: ctrl+shift+9
3054 nth_window
3056 Focus the nth window if positive or the previously active windows if
3058 negative. When the number is larger
3059 than the number of windows focus the last window. For example:
3061 # focus the previously active window
3063 map ctrl+p nth_window -1
3064 # focus the first window
3065 map ctrl+1 nth_window 0
3066 previous_window
3068 Focus the previous window in the current tab
3070 Default shortcuts using this action: ctrl+shift+[
3072 reset_window_sizes
3074 Reset window sizes undoing any dynamic resizing of windows
3076 resize_window
3078 Resize the active window by the specified amount
3080 See Resizing windows for details.
3082 second_window
3084 Focus the second window
3086 Default shortcuts using this action: ctrl+shift+2
3088 seventh_window
3090 Focus the seventh window
3092 Default shortcuts using this action: ctrl+shift+7
3094 sixth_window
3096 Focus the sixth window
3098 Default shortcuts using this action: ctrl+shift+6
3100 swap_with_window
3102 Swap the current window with another window in the current tab, se‐
3104 lected visually. See visual_window_select_characters
3105 Default shortcuts using this action: ctrl+shift+f8
3107 tenth_window
3109 Focus the tenth window
3111 Default shortcuts using this action: ctrl+shift+0
3113 third_window
3115 Focus the third window
3117 Default shortcuts using this action: ctrl+shift+3
3119 change_font_size
3121 Change the font size for the current or all OS Windows
3123 See Font sizes for details.
3125 Default shortcuts using this action: ctrl+shift+minus,
3127 ctrl+shift+equal, ctrl+shift+backspace
3128 close_os_window
3130 Close the currently active OS Window
3132 Default shortcuts using this action: shift+cmd+w
3134 close_window
3136 Close the currently active window
3138 Default shortcuts using this action: ctrl+shift+w
3140 close_window_with_confirmation
3142 Close window with confirmation
3144 Asks for confirmation before closing the window. If you don't want the
3146 confirmation when the window is sitting at a shell prompt (requires
3147 Shell integration), use:
3148 map f1 close_window_with_confirmation ignore-shell
3150 detach_window
3152 Detach a window, moving it to another tab or OS Window
3154 See detaching windows for details.
3156 new_os_window
3158 New OS Window
3160 Default shortcuts using this action: ctrl+shift+n
3162 new_os_window_with_cwd
3164 New OS Window with the same working directory as the currently active
3166 window
3167 new_window
3169 Create a new window
3171 Default shortcuts using this action: ctrl+shift+enter
3173 new_window_with_cwd
3175 Create a new window with working directory same as that of the active
3177 window
3178 nth_os_window
3180 Focus the nth OS window
3182 quit
3184 Quit, closing all windows
3186 set_background_opacity
3188 Set the background opacity for the active OS Window
3190 For example:
3192 map f1 set_background_opacity +0.1
3194 map f2 set_background_opacity -0.1
3195 map f3 set_background_opacity 0.5
3196 Default shortcuts using this action: ctrl+shift+a>l, ctrl+shift+a>1,
3198 ctrl+shift+a>m, ctrl+shift+a>d
3199 start_resizing_window
3201 Resize the active window interactively
3203 See Resizing windows for details.
3205 Default shortcuts using this action: ctrl+shift+r
3207 toggle_fullscreen
3209 Toggle the fullscreen status of the active OS Window
3211 Default shortcuts using this action: ctrl+shift+f11
3213 toggle_maximized
3215 Toggle the maximized status of the active OS Window
3217 Default shortcuts using this action: ctrl+shift+f10
3219
3221 Kovid Goyal
3222
3224 2022, Kovid Goyal
32250.26.5 Nov 07, 2022 KITTY.CONF(5)