Glossary

os_window

kitty has two kinds of windows. Operating System windows, referred to as OS Window, and kitty windows. An OS Window consists of one or more kitty tabs. Each tab in turn consists of one or more kitty windows organized in a layout.

tab

A tab refers to a group of kitty windows, organized in a layout. Every OS Window contains one or more tabs.

layout

A layout is a system of organizing kitty windows in groups inside a tab. The layout automatically maintains the size and position of the windows, think of a layout as a tiling window manager for the terminal. See Arrange windows for details.

window

kitty has two kinds of windows. Operating System windows, referred to as OS Window, and kitty windows. An OS Window consists of one or more kitty tabs. Each tab in turn consists of one or more kitty windows organized in a layout.

overlay

An overlay window is a kitty window that is placed on top of an existing kitty window, entirely covering it. Overlays are used throughout kitty, for example, to display the the scrollback buffer, to display hints, for unicode input etc. Normal overlays are meant for short duration popups and so are not considered the active window when determining the current working directory or getting input text for kittens, launch commands, etc. To create an overlay considered as a main window use the overlay-main argument to The launch command.

Terminals can have hyperlinks, just like the internet. In kitty you can control exactly what happens when clicking on a hyperlink, based on the type of link and its URL. See also Hyperlinks in terminal emulators.

kittens

Small, independent statically compiled command line programs that are designed to run inside kitty windows and provide it with lots of powerful and flexible features such as viewing images, connecting conveniently to remote computers, transferring files, inputting unicode characters, etc.

Environment variables

Variables that influence kitty behavior

KITTY_CONFIG_DIRECTORY

Controls where kitty looks for kitty.conf and other configuration files. Defaults to ~/.config/kitty. For full details of the config directory lookup mechanism see, kitty --config.

KITTY_CACHE_DIRECTORY

Controls where kitty stores cache files. Defaults to ~/.cache/kitty or ~/Library/Caches/kitty on macOS.

KITTY_RUNTIME_DIRECTORY

Controls where kitty stores runtime files like sockets. Defaults to the XDG_RUNTIME_DIR environment variable if that is defined otherwise the run directory inside the kitty cache directory is used.

VISUAL

The terminal based text editor (such as vi or nano) kitty uses, when, for instance, opening kitty.conf in response to ctrl+shift+f2.

EDITOR

Same as VISUAL. Used if VISUAL is not set.

GLFW_IM_MODULE

Set this to ibus to enable support for IME under X11.

KITTY_WAYLAND_DETECT_MODIFIERS

When set to a non-empty value, kitty attempts to autodiscover XKB modifiers under Wayland. This is useful if using non-standard modifiers like hyper. It is possible for the autodiscovery to fail; the default Wayland XKB mappings are used in this case. See #3943 for details.

SSH_ASKPASS

Specify the program for SSH to ask for passwords. When this is set, ssh kitten will use this environment variable by default. See askpass for details.

KITTY_CLONE_SOURCE_CODE

Set this to some shell code that will be executed in the cloned window with eval when clone-in-kitty is used.

KITTY_CLONE_SOURCE_PATH

Set this to the path of a file that will be sourced in the cloned window when clone-in-kitty is used.

KITTY_DEVELOP_FROM

Set this to the directory path of the kitty source code and its Python code will be loaded from there. Only works with official binary builds.

KITTY_RC_PASSWORD

Set this to a pass phrase to use the kitten @ remote control command with remote_control_password.

Variables that kitty sets when running child programs

LANG

This is only set on macOS. If the country and language from the macOS user settings form an invalid locale, it will be set to en_US.UTF-8.

PATH

kitty prepends itself to the PATH of its own environment to ensure the functions calling kitty will work properly.

KITTY_WINDOW_ID

An integer that is the id for the kitty window the program is running in. Can be used with the kitty remote control facility.

KITTY_PID

An integer that is the process id for the kitty process in which the program is running. Allows programs to tell kitty to reload its config by sending it the SIGUSR1 signal.

KITTY_PUBLIC_KEY

A public key that programs can use to communicate securely with kitty using the remote control protocol. The format is: protocol:key data.

WINDOWID

The id for the OS Window the program is running in. Only available on platforms that have ids for their windows, such as X11 and macOS.

TERM

The name of the terminal, defaults to xterm-kitty. See term.

TERMINFO

Path to a directory containing the kitty terminfo database. Or the terminfo database itself encoded in base64. See terminfo_type.

KITTY_INSTALLATION_DIR

Path to the kitty installation directory.

COLORTERM

Set to the value truecolor to indicate that kitty supports 16 million colors.

KITTY_LISTEN_ON

Set when the remote control facility is enabled and the a socket is used for control via kitty --listen-on or listen_on. Contains the path to the socket. Avoid the need to use kitten @ --to when issuing remote control commands. Can also be a file descriptor of the form fd:num instead of a socket address, in which case, remote control communication should proceed over the specified file descriptor.

KITTY_PIPE_DATA

Set to data describing the layout of the screen when running child programs using launch --stdin-source with the contents of the screen/scrollback piped to them.

KITTY_CHILD_CMDLINE

Set to the command line of the child process running in the kitty window when calling the notification callback program on terminal bell, see command_on_bell.

KITTY_COMMON_OPTS

Set with the values of some common kitty options when running kittens, so kittens can use them without needing to load kitty.conf.

KITTY_SHELL_INTEGRATION

Set when enabling Shell integration. It is automatically removed by the shell integration scripts.

ZDOTDIR

Set when enabling Shell integration with zsh, allowing zsh to automatically load the integration script.

XDG_DATA_DIRS

Set when enabling Shell integration with fish, allowing fish to automatically load the integration script.

ENV

Set when enabling Shell integration with bash, allowing bash to automatically load the integration script.

KITTY_OS

Set when using the include directive in kitty.conf. Can take values: linux, macos, bsd.

KITTY_HOLD

Set to 1 when kitty is running a shell because of the --hold flag. Can be used to specialize shell behavior in the shell rc files as desired.

KITTY_SIMD

Set it to 128 to use 128 bit vector registers, 256 to use 256 bit vector registers or any other value to prevent kitty from using SIMD CPU vector instructions. Warning, this overrides CPU capability detection so will cause kitty to crash with SIGILL if your CPU does not support the necessary SIMD extensions.