kitty.conf

.. highlight:: conf

.. only:: man

Overview
--------------

|kitty| is highly customizable, everything from keyboard shortcuts, to rendering frames-per-second. See below for an overview of all customization possibilities.

You can open the config file within |kitty| by pressing :sc:edit_config_file (:kbd:⌘+, on macOS). A :file:kitty.conf with commented default configurations and descriptions will be created if the file does not exist. You can reload the config file within |kitty| by pressing :sc:reload_config_file (:kbd:⌃+⌘+, on macOS) or sending |kitty| the SIGUSR1 signal with kill -SIGUSR1 $KITTY_PID. You can also display the current configuration by pressing :sc:debug_config (:kbd:⌥+⌘+, on macOS).

.. _confloc:

|kitty| looks for a config file in the OS config directories (usually :file:~/.config/kitty/kitty.conf) but you can pass a specific path via the :option:kitty --config option or use the :envvar:KITTY_CONFIG_DIRECTORY environment variable. See :option:kitty --config for full details.

Comments can be added to the config file as lines starting with the # character. This works only if the # character is the first character in the line.

Lines can be split by starting the next line with the \ character. All leading whitespace and the \ character are removed.

.. _include:

You can include secondary config files via the :code:include directive. If you use a relative path for :code:include, it is resolved with respect to the location of the current config file. Note that environment variables are expanded, so :code:${USER}.conf becomes :file:name.conf if :code:USER=name. A special environment variable :envvar:KITTY_OS is available, to detect the operating system. It is linux, macos or bsd. Also, you can use :code:globinclude to include files matching a shell glob pattern and :code:envinclude to include configuration from environment variables. Finally, you can dynamically generate configuration by running a program using :code:geninclude. For example::

 # Include other.conf
 include other.conf
 # Include *.conf files from all subdirs of kitty.d inside the kitty config dir
 globinclude kitty.d/**/*.conf
 # Include the *contents* of all env vars starting with KITTY_CONF_
 envinclude KITTY_CONF_*
 # Run the script dynamic.py placed in the same directory as this config file
 # and include its :file:`STDOUT`. Note that Python scripts are fastest
 # as they use the embedded Python interpreter, but any executable script
 # or program is supported, in any language. Remember to mark the script
 # file executable.
 geninclude dynamic.py

.. include:: /generated/conf-kitty.rst

Sample kitty.conf

.. only:: html

You can download a sample :file:`kitty.conf` file with all default settings
and comments describing each setting by clicking: :download:`sample
kitty.conf </generated/conf/kitty.conf>`.

.. only:: man

You can edit a fully commented sample kitty.conf by pressing the :sc:edit_config_file shortcut in kitty. This will generate a config file with full documentation and all settings commented out. If you have a pre-existing :file:kitty.conf, then that will be used instead, delete it to see the sample file.

A default configuration file can also be generated by running::

kitty +runpy 'from kitty.config import *; print(commented_out_default_config())'

This will print the commented out default config file to :file:STDOUT.

All mappable actions

See the :doc:list of all the things you can make |kitty| can do </actions>.

.. toctree:: :hidden:

actions wide-gamut-colors