Frequently Asked Questions (2024)

Some special symbols are rendered small/truncated in kitty?¶

The number of cells a Unicode character takes up are controlled by the Unicodestandard. All characters are rendered in a single cell unless the Unicodestandard says they should be rendered in two cells. When a symbol does not fit,it will either be rescaled to be smaller or truncated (depending on how muchextra space it needs). This is often different from other terminals which justlet the character overflow into neighboring cells, which is fine if theneighboring cell is empty, but looks terrible if it is not.

Some programs, like Powerline, vim with fancy gutter symbols/status-bar, etc.use Unicode characters from the private use area to represent symbols. Oftenthese symbols are wide and should be rendered in two cells. However, sinceprivate use area symbols all have their width set to one in the Unicodestandard, kitty renders them either smaller or truncated. The exception is ifthese characters are followed by a space or en-space (U+2002) in which casekitty makes use of the extra cell to render them in two cells. This behaviorcan be turned off for specific symbols using narrow_symbols.

Using a color theme with a background color does not work well in vim?¶

Sadly, vim has very poor out-of-the-box detection for modern terminal features.Furthermore, it recently broke detection even more.It kind of, but not really, supports terminfo, except it overrides it with its own hard-codedvalues when it feels like it. Worst of all, it has no ability to detect modernfeatures not present in terminfo, at all, even security sensitive ones likebracketed paste.

Thankfully, probably as a consequence of this lack of detection, vim allows users toconfigure these low level details. So, to make vim work well with any modernterminal, including kitty, add the following to your ~/.vimrc.

" Mouse supportset mouse=aset ttymouse=sgrset balloonevalterm" Styled and colored underline supportlet &t_AU = "\e[58:5:%dm"let &t_8u = "\e[58:2:%lu:%lu:%lum"let &t_Us = "\e[4:2m"let &t_Cs = "\e[4:3m"let &t_ds = "\e[4:4m"let &t_Ds = "\e[4:5m"let &t_Ce = "\e[4:0m"" Strikethroughlet &t_Ts = "\e[9m"let &t_Te = "\e[29m"" Truecolor supportlet &t_8f = "\e[38:2:%lu:%lu:%lum"let &t_8b = "\e[48:2:%lu:%lu:%lum"let &t_RF = "\e]10;?\e\\"let &t_RB = "\e]11;?\e\\"" Bracketed pastelet &t_BE = "\e[?2004h"let &t_BD = "\e[?2004l"let &t_PS = "\e[200~"let &t_PE = "\e[201~"" Cursor controllet &t_RC = "\e[?12$p"let &t_SH = "\e[%d q"let &t_RS = "\eP$q q\e\\"let &t_SI = "\e[5 q"let &t_SR = "\e[3 q"let &t_EI = "\e[1 q"let &t_VS = "\e[?12l"" Focus trackinglet &t_fe = "\e[?1004h"let &t_fd = "\e[?1004l"execute "set <FocusGained>=\<Esc>[I"execute "set <FocusLost>=\<Esc>[O"" Window titlelet &t_ST = "\e[22;2t"let &t_RT = "\e[23;2t"" vim hardcodes background color erase even if the terminfo file does" not contain bce. This causes incorrect background rendering when" using a color theme with a background color in terminals such as" kitty that do not support background color erase.let &t_ut=''

These settings must be placed before setting the colorscheme. It isalso important that the value of the vim term variable is not changedafter these settings.

I get errors about the terminal being unknown or opening the terminal failing or functional keys like arrow keys don’t work?¶

These issues all have the same root cause: the kitty terminfo files not beingavailable. The most common way this happens is SSHing into a computer that doesnot have the kitty terminfo files. The simplest fix for that is running:

kitten ssh myserver

It will automatically copy over the terminfo files and also magically enableshell integration on the remote machine.

This ssh kitten takes all the same command line argumentsas ssh, you can alias it to something small in your shell’s rc filesto avoid having to type it each time:

alias s="kitten ssh"

If this does not work, see Copying terminfo files manually for alternative ways toget the kitty terminfo files onto a remote computer.

The next most common reason for this is if you are running commands as rootusing sudo or su. These programs often filter theTERMINFO environment variable which is what points to the kittyterminfo files.

First, make sure the TERM is set to xterm-kitty in the sudoenvironment. By default, it should be automatically copied over.

If you are using a well maintained Linux distribution, it will have akitty-terminfo package that you can simply install to make the kittyterminfo files available system-wide. Then the problem will no longer occur.

Alternately, you can configure sudo to preserve TERMINFOby running sudo visudo and adding the following line:

Defaults env_keep += "TERM TERMINFO"

If none of these are suitable for you, you can run sudo as

sudo TERMINFO="$TERMINFO"

This will make TERMINFO availablein the sudo environment. Create an alias in your shell rc files to make thisconvenient:

alias sudo="sudo TERMINFO=\"$TERMINFO\""

If you have double width characters in your prompt, you may also need toexplicitly set a UTF-8 locale, like:

export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8

I cannot use the key combination X in program Y?¶

First, run:

kitten show-key -m kitty

Press the key combination X. If the kitten reports the key pressthat means kitty is correctly sending the key press to terminal programs.You need to report the issue to the developer of the terminal program. Mostlikely they have not added support for Comprehensive keyboard handling in terminals.

If the kitten does not report it, it means that the key is bound to some actionin kitty. You can unbind it in kitty.conf with:

map X no_op

Here X is the keys you press on the keyboard. So for examplectrl+shift+1.

How do I change the colors in a running kitty instance?¶

The easiest way to do it is to use the themes kitten,to choose a new color theme. Simply run:

kitten themes

And choose your theme from the list.

You can also define keyboard shortcuts to set colors, for example:

map f1 set_colors --configured /path/to/some/config/file/colors.conf

Or you can enable remote control for kitty and usekitten @ set-colors. The shortcut mapping technique has the same syntax as theremote control command, for details, see kitten @ set-colors.

To change colors when SSHing into a remote host, use the color_scheme setting for the ssh kitten.

Additionally, You can use theOSC terminal escape codesto set colors. Examples of using OSC escape codes to set colors:

Change the default foreground color:printf '\x1b]10;#ff0000\x1b\\'Change the default background color:printf '\x1b]11;blue\x1b\\'Change the cursor color:printf '\x1b]12;blue\x1b\\'Change the selection background color:printf '\x1b]17;blue\x1b\\'Change the selection foreground color:printf '\x1b]19;blue\x1b\\'Change the nth color (0 - 255):printf '\x1b]4;n;green\x1b\\'

You can use various syntaxes/names for color specifications in the aboveexamples. See XParseColorfor full details.

If a ? is given rather than a color specification, kitty will respondwith the current value for the specified color.

How do I specify command line options for kitty on macOS?¶

Apple does not want you to use command line options with GUI applications. Toworkaround that limitation, kitty will read command line options from the file<kitty config dir>/macos-launch-services-cmdline when it is launchedfrom the GUI, i.e. by clicking the kitty application icon or usingopen -a kitty. Note that this file is only read when running via the GUI.

You can, of course, also run kitty from a terminal with command line options,using: /Applications/kitty.app/Contents/MacOS/kitty.

And within kitty itself, you can always run kitty using just kitty as itcleverly adds itself to the PATH.

I catted a binary file and now kitty is hung?¶

Never output unknown binary data directly into a terminal.

Terminals have a single channel for both data and control. Certain bytesare control codes. Some of these control codes are of arbitrary length, so ifthe binary data you output into the terminal happens to contain the startingsequence for one of these control codes, the terminal will hang waiting for theclosing sequence. Press ctrl+shift+delete to reset the terminal.

If you do want to cat unknown data, use cat -v.

kitty is not able to use my favorite font?¶

kitty achieves its stellar performance by caching alpha masks of each renderedcharacter on the GPU, and rendering them all in parallel. This means it is astrictly character cell based display. As such it can use only monospace fonts,since every cell in the grid has to be the same size. Furthermore, it needsfonts to be freely resizable, so it does not support bitmapped fonts.

# Nerd Fonts v3.1.0symbol_map U+e000-U+e00a,U+ea60-U+ebeb,U+e0a0-U+e0c8,U+e0ca,U+e0cc-U+e0d4,U+e200-U+e2a9,U+e300-U+e3e3,U+e5fa-U+e6b1,U+e700-U+e7c5,U+f000-U+f2e0,U+f300-U+f372,U+f400-U+f532,U+f0001-U+f1af0 Symbols Nerd Font Mono

If your font is not listed in kitty +list-fonts it means that it is notmonospace or is a bitmapped font. On Linux you can list all monospace fontswith:

fc-list : family spacing outline scalable | grep -e spacing=100 -e spacing=90 | grep -e outline=True | grep -e scalable=True

Note that the spacing property is calculated by fontconfig based on actual glyphwidths in the font. If for some reason fontconfig concludes your favoritemonospace font does not have spacing=100 you can override it by using thefollowing ~/.config/fontconfig/fonts.conf:

<?xml version="1.0"?><!DOCTYPE fontconfig SYSTEM "fonts.dtd"><fontconfig><match target="scan"> <test name="family"> <string>Your Font Family Name</string> </test> <edit name="spacing"> <int>100</int> </edit></match></fontconfig>

After creating (or modifying) this file, you may need to run the followingcommand to rebuild your fontconfig cache:

fc-cache -r

Then, the font will be available in kitty +list-fonts.

How can I assign a single global shortcut to bring up the kitty terminal?¶

Bringing up applications on a single key press is the job of the windowmanager/desktop environment. For ways to do it with kitty (or indeed anyterminal) in different environments,see here.

I do not like the kitty icon!¶

There are many alternate icons available, click on an icon to visit itshomepage:

On macOS and X11 you can put kitty.app.icns (macOS only) or kitty.app.png in thekitty configuration directory, and this icon will be appliedautomatically at startup. On X11, this will set the icon for kitty windows.

Unfortunately, on macOS, Apple’s Dock does not change its cached icon so thecustom icon will revert when kitty is quit. Run the following to force the Dockto update its cached icons:

rm /var/folders/*/*/*/com.apple.dock.iconcache; killall Dock

If you prefer not to keep a custom icon in the kitty config folder, on macOS, you canalso set it with the following command:

# Set kitty.icns as the icon for currently running kittykitty +runpy 'from kitty.fast_data_types import cocoa_set_app_icon; import sys; cocoa_set_app_icon(*sys.argv[1:]); print("OK")' kitty.icns# Set the icon for app bundle specified by the pathkitty +runpy 'from kitty.fast_data_types import cocoa_set_app_icon; import sys; cocoa_set_app_icon(*sys.argv[1:]); print("OK")' /path/to/icon.png /Applications/kitty.app

You can also change the icon manually by following the steps:

1. Find kitty.app in the Applications folder, select it and press ⌘+I

2. Drag kitty.icns onto the application icon in the kitty info pane

3. Delete the icon cache and restart Dock:

rm /var/folders/*/*/*/com.apple.dock.iconcache; killall Dock

How do I map key presses in kitty to different keys in the terminal program?¶

This is accomplished by using map with send_key in kitty.conf.For example:

map alt+s send_key ctrl+s

This causes the program running in kitty to receive the ctrl+s key whenyou press the alt+s key. To see this in action, run:

kitten show-key -m kitty

Which will print out what key events it receives. To send arbitrary text ratherthan a key press, see send_text instead.

How do I open a new window or tab with the same working directory as the current window?¶

In kitty.conf add the following:

map f1 launch --cwd=currentmap f2 launch --cwd=current --type=tab

Pressing F1 will open a new kitty window with the same working directoryas the current window. The launch command is very powerful,explore its documentation.

Things behave differently when running kitty from system launcher vs. from another terminal?¶

This will be because of environment variables. When you run kitty from thesystem launcher, it gets a default set of system environment variables. Whenyou run kitty from another terminal, you are actually running it from a shell,and the shell’s rc files will have setup a whole different set of environmentvariables which kitty will now inherit.

You need to make sure that the environment variables you define in your shell’src files are either also defined system wide or via the env directive inkitty.conf. Common environment variables that cause issues are thoserelated to localization, such as LANG, LC_* and loading ofconfiguration files such as XDG_*, KITTY_CONFIG_DIRECTORY.

To see the environment variables that kitty sees, you can add the followingmapping to kitty.conf:

map f1 show_kitty_env_vars

then pressing F1 will show you the environment variables kitty sees.

This problem is most common on macOS, as Apple makes it exceedingly difficult tosetup environment variables system-wide, so people end up putting them in allsorts of places where they may or may not work.

I am using tmux and have a problem¶

First, terminal multiplexers are a bad idea,do not use them, if at all possible. kitty contains features that do all of whattmux does, but better, with the exception of remote persistence (#391).If you still want to use tmux, read on.

Using ancient versions of tmux such as 1.8 will cause gibberish on screen whenpressing keys (#3541).

If you are using tmux with multiple terminals or you start it under one terminaland then switch to another and these terminals have different TERMvariables, tmux will break. You will need to restart it as tmux does not supportmultiple terminfo definitions.

Displaying images while inside programs such as nvim or ranger may not workdepending on whether those programs have adopted support for the unicodeplaceholders workaround that kitty createdfor tmux refusing to support images.

If you use any of the advanced features that kitty has innovated, such asstyled underlines, desktop notifications, extended keyboard support, file transfer, the sshkitten, shell integration etc. they may or may not work,depending on the whims of tmux’s maintainer, your version of tmux, etc.

I opened and closed a lot of windows/tabs and top shows kitty’s memory usage is very high?¶

top is not a good way to measure process memory usage. That isbecause on modern systems, when allocating memory to a process, the C libraryfunctions will typically allocate memory in large blocks, and give the processchunks of these blocks. When the process frees a chunk, the C library will notnecessarily release the underlying block back to the OS. So even though theapplication has released the memory, top will still claim the processis using it.

To check for memory leaks, instead use a tool like Valgrind. Run:

PYTHONMALLOC=malloc valgrind --tool=massif kitty

Now open lots of tabs/windows, generate lots of output using tools like find/yesetc. Then close all but one window. Do some random work for a few seconds inthat window, maybe run yes or find again. Then quit kitty and run:

massif-visualizer massif.out.*

You will see the allocations graph goes up when you opened the windows, thengoes back down when you closed them, indicating there were no memory leaks.

For those interested, you can get a similar profile out of valgrindas you get with top by adding --pages-as-heap=yes then you willsee that memory allocated in malloc is not freed in free. This can be furtherrefined if you use glibc as your C library by setting the environmentvariable MALLOC_MMAP_THRESHOLD_=64. This will cause free to actually freememory allocated in sizes of more than 64 bytes. With this set, memory usagewill climb high, then fall when closing windows, but not fall all the way back.The remaining used memory can be investigated using valgrind again, and it willcome from arenas in the GPU drivers and the per thread arenas glibc’s mallocmaintains. These too allocate memory in large blocks and don’t release it backto the OS immediately.

Why does kitty sometimes start slowly on my Linux system?¶

kitty takes no longer (within 100ms) to start than other similar GPU terminalemulators, (and may be faster than some). If kitty occasionally takes a longtime to start, it could be a power management issue with the graphics card. Ona multi-GPU system (which many modern laptops are, having a power efficient GPUthat’s built into the processor and a power hungry dedicated one that’s usuallyoff), even if the answer of the GPU will only be “don’t use me”.

For example, if you have a system with an AMD CPU and an NVIDIA GPU, and youknow that you want to use the lower powered card to save battery life andbecause kitty does not require a powerful GPU to function, you can choose notto wake up the dedicated card, which has been reported on at least one system(#4292) to take ≈2 seconds, by running kitty as:

MESA_LOADER_DRIVER_OVERRIDE=radeonsi __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/50_mesa.json kitty

The correct command will depend on your situation and hardware.__EGL_VENDOR_LIBRARY_FILENAMES instructs the GL dispatch library to uselibEGL_mesa.so and ignore libEGL_nvidia.so also available on thesystem, which will wake the NVIDIA card during device enumeration.MESA_LOADER_DRIVER_OVERRIDE also assures that Mesa won’t offer any NVIDIAcard during enumeration, and will instead just use radeonsi_dri.so.