Configure Kitty (Including Image Protocol)

Kitty is a GPU-accelerated terminal emulator that renders through OpenGL, supports true colour, ligatures, and — most distinctively — a native graphics protocol that lets programs draw pixel images directly in the terminal. This guide walks through installing Kitty, writing a useful kitty.conf, applying themes, working with splits and windows, using kittens (Kitty's built-in scripting helpers), and enabling the graphics protocol for tools like ranger, viu, and Neovim image plugins.

Installation

Kitty packages in some distro repos lag behind; the upstream installer is the recommended path for the latest version and full feature support.

Upstream installer (all distros)

curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin

This installs to ~/.local/kitty.app/ and creates a desktop entry. Add the binary to your PATH:

ln -sf ~/.local/kitty.app/bin/kitty ~/.local/bin/kitty
ln -sf ~/.local/kitty.app/bin/kitten ~/.local/bin/kitten

Distro packages

# Debian / Ubuntu
sudo apt install kitty

# Fedora
sudo dnf install kitty

# Arch
sudo pacman -S kitty

Verify the version after installing:

kitty --version
# kitty 0.35.2 created by Kovid Goyal

kitty.conf Basics

Kitty reads ~/.config/kitty/kitty.conf on startup. If the file does not exist, Kitty uses built-in defaults. Create the directory and an initial config:

mkdir -p ~/.config/kitty
touch ~/.config/kitty/kitty.conf

A solid starting configuration covers font, appearance, scrollback, and behaviour:

cat >> ~/.config/kitty/kitty.conf << 'EOF'
# --- Font ---
font_family      JetBrainsMono Nerd Font
bold_font        auto
italic_font      auto
font_size        13.0

# --- Cursor ---
cursor_shape     block
cursor_blink_interval 0

# --- Scrollback ---
scrollback_lines 10000
scrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS +INPUT_LINE_NUMBER

# --- Window ---
window_padding_width 6
hide_window_decorations no

# --- Bell ---
enable_audio_bell no
visual_bell_duration 0.1

# --- Tab bar ---
tab_bar_style    powerline
tab_powerline_style round

# --- Performance ---
repaint_delay    8
input_delay      1
sync_to_monitor  yes
EOF

Reload the config without restarting: press Ctrl+Shift+F5, or run:

kill -SIGUSR1 $(pgrep -f 'kitty')

Applying Themes

Kitty ships a built-in theme browser since version 0.23. Run the interactive picker:

kitty +kitten themes

Browse with arrow keys, preview live, and press Enter to apply. The kitten writes an include current-theme.conf line into your kitty.conf and saves the theme file to ~/.config/kitty/current-theme.conf.

To set a specific theme non-interactively:

kitty +kitten themes --cache-age=0 "Gruvbox Dark"

You can also drop any .conf colour scheme file into ~/.config/kitty/ and include it manually:

echo 'include ~/.config/kitty/mytheme.conf' >> ~/.config/kitty/kitty.conf

Splits, Windows, and Tabs

Kitty calls its split panes windows and groups them into OS windows or tabs. No plugin is required — it is all built in.

Default keyboard shortcuts

• Ctrl+Shift+Enter — new window (split) in current tab
• Ctrl+Shift+T — new tab
• Ctrl+Shift+[ / ] — move between windows
• Ctrl+Shift+R — enter resize mode for windows
• Ctrl+Shift+Alt+T — rename current tab

Choosing a layout

Kitty supports several layouts: tall, fat, grid, splits, stack. Add this to kitty.conf to enable the flexible splits layout by default and bind a key to rotate through them:

cat >> ~/.config/kitty/kitty.conf << 'EOF'
enabled_layouts splits,stack,tall,grid
map ctrl+shift+l next_layout
EOF

Inside the splits layout you can open windows horizontally or vertically with distinct maps:

cat >> ~/.config/kitty/kitty.conf << 'EOF'
map ctrl+shift+- launch --location=hsplit
map ctrl+shift+\ launch --location=vsplit
EOF

Kittens

Kittens are small Python or built-in programs that extend Kitty without external dependencies. They run as kitty +kitten <name>.

Useful built-in kittens

• icat — display images inline (see next section)
• diff — side-by-side diff with syntax highlighting: kitty +kitten diff file1 file2
• ssh — forwards Kitty's terminfo and shell integration over SSH automatically: kitty +kitten ssh user@host
• hints — select URLs, file paths, word fragments from the terminal buffer with the keyboard
• clipboard — read/write the clipboard from scripts: echo hello | kitty +kitten clipboard
• themes — covered above

Binding kittens to keys

cat >> ~/.config/kitty/kitty.conf << 'EOF'
# Open URL hints with Ctrl+Shift+U
map ctrl+shift+u kitten hints --type url --program browser

# Quick SSH kitten alias
map ctrl+shift+s launch --type=tab kitty +kitten ssh
EOF

The Kitty Graphics Protocol

The Kitty graphics protocol (KGP) lets terminal applications transmit pixel images to the terminal emulator over the PTY using base64-encoded chunks and control sequences. Unlike sixel, KGP supports true 32-bit RGBA, asynchronous rendering, and compositing. Programs must explicitly support it.

Test with icat

kitty +kitten icat /path/to/image.png

If you see the image rendered in the terminal without artefacts, the graphics protocol is working. This also works over SSH when you connect with kitty +kitten ssh.

viu — quick image viewer

viu auto-detects Kitty and uses KGP:

# Install
cargo install viu          # Rust toolchain required
# or on Arch
sudo pacman -S viu

# Use
viu image.jpg

ranger preview with ueberzugpp

Install ueberzugpp, which supports the Kitty protocol natively:

# Arch
sudo pacman -S ueberzugpp

# Debian / Ubuntu (build from source or use the AUR equivalent PPA)
sudo apt install ueberzugpp

In your ranger rc.conf, set:

set preview_images true
set preview_images_method ueberzugpp

Neovim image support

Plugins such as 3rd/image.nvim use KGP. Install via your plugin manager and set the backend:

require('image').setup({
  backend = 'kitty',
})

No extra Kitty config is needed — KGP is always enabled as long as Kitty is the terminal.

Verification

Run a quick sanity check across the features you have configured:

# Check version and OpenGL renderer
kitty --version
kitty +runpy 'from kitty.fast_data_types import opengl_version_string; print(opengl_version_string())'

# Confirm graphics protocol works
kitty +kitten icat --align=left ~/.local/kitty.app/share/icons/hicolor/256x256/apps/kitty.png

# Confirm SSH kitten forwards terminfo
kitty +kitten ssh localhost -- infocmp xterm-kitty | head -3

Troubleshooting

Images do not display with icat

You are likely running Kitty inside tmux or another multiplexer. KGP does not pass through multiplexers by default. Run Kitty's native splits instead, or use Kitty's kitten ssh which handles forwarding. Check with echo $TERM — it should read xterm-kitty.

Font glyphs are missing or incorrect

Install a Nerd Font and reference it exactly as fc-list reports it:

fc-list | grep -i jetbrains

Copy the exact family name into font_family in kitty.conf.

kitty.conf changes not taking effect

Some options (like font_family) require a full restart; Ctrl+Shift+F5 only reloads a subset. Close and reopen Kitty if a setting seems stuck.

TERM is wrong in remote shells

The xterm-kitty terminfo entry may not exist on the remote host. Use the SSH kitten (kitty +kitten ssh) which copies the terminfo automatically, or manually copy it:

infocmp xterm-kitty | ssh user@host 'tic -x /dev/stdin'