The Kitty package in your distro repo can be seventeen releases behind upstream. On Ubuntu 24.04 and Linux Mint, apt install kitty gives you a build from early 2024 that has no font picker, no command palette and no cursor trail. Arch is current to the day. Fedora, Debian and Ubuntu 26.04 sit in between. Where your distro lands decides how you should install Kitty terminal in the first place.
This guide covers every install path that works: apt on Ubuntu, Debian and Mint, dnf on Fedora, pacman on Arch, Homebrew on macOS, and the official binary installer for the latest release on any of them. After that we configure kitty.conf, switch themes with the themes kitten, build a splits layout, fix the xterm-kitty SSH error and drive Kitty from scripts. Every command was run on Ubuntu 26.04 and 24.04, Debian 13, Fedora 44, Arch Linux, Linux Mint 22.3 and macOS 26 in October 2026, with Kitty 0.49.2 from the official installer as the reference build.
Which Kitty version each distro ships
We installed Kitty from the default repos on fresh VMs and recorded what landed. The last two columns are the features people search for most once Kitty is running.
| Platform | Install command | Kitty version | kitten choose-fonts | Command palette |
|---|---|---|---|---|
| Arch Linux | pacman -S kitty | 0.49.2 | Yes | Yes |
| macOS (Homebrew cask) | brew install --cask kitty | 0.49.2 | Yes | Yes |
| Fedora 45 Beta | dnf install kitty | 0.48.2 | Yes | Yes |
| Fedora 44 | dnf install kitty | 0.47.1 | Yes | Yes |
| Ubuntu 26.04 LTS | apt install kitty | 0.45.0 | Yes | No |
| Debian 13 | apt install kitty | 0.41.1 | Yes | No |
| Ubuntu 24.04 LTS | apt install kitty | 0.32.2 | No | No |
| Linux Mint 22.3 | apt install kitty | 0.32.2 | No | No |
| Official installer (any Linux, macOS) | curl ... | sh | 0.49.2 | Yes | Yes |
The short version: on Arch, Fedora and macOS the package manager is fine. On Ubuntu 24.04, Mint and Debian, use the official installer if you want current features and security fixes. The latest release also patched a file transfer issue where a program on a remote host could skip the confirmation prompt; older distro builds get that fix only if their maintainers backport it.
Install Kitty on Ubuntu, Debian and Linux Mint
Kitty lives in universe on Ubuntu and in main on Debian. One command on all three:
sudo apt update && sudo apt install -y kittyUbuntu pulls in kitty-terminfo, kitty-shell-integration and kitty-doc alongside the main package. Confirm the build you got:
kitty --versionUbuntu 26.04 reports this version:
kitty 0.45.0 created by Kovid GoyalUbuntu 24.04 and Linux Mint 22.3 print kitty 0.32.2 instead, and Debian 13 prints kitty 0.41.1. If that’s too old for you, skip ahead to the official installer. It installs into your home directory and coexists with the apt package without conflicts.
Halve the launch time of the Ubuntu 26.04 package
The Ubuntu 26.04 package ships no optimized bytecode. Kitty runs its Python code with -OO, finds no .opt-2.pyc files, and tries to write them into /usr/lib/kitty on every launch. As a normal user that fails, so strace shows 135 EACCES errors per start and Kitty compiles everything again in memory. Compile the bytecode once as root:
sudo python3 -OO -m compileall -q /usr/lib/kittyOn our GNOME VM (software rendering, so the absolute numbers are high) launch to exit dropped from about 1.2 seconds to about 0.6 seconds, measured over six runs each. The official installer build already ships compiled bytecode and came in at roughly 0.4 seconds on the same VM. A package upgrade replaces the source files and makes the compiled files stale, so rerun the command after apt upgrade updates Kitty. Our terminal emulator benchmark measured the same problem as first-frame latency.
Install Kitty on Fedora
Fedora packages Kitty in the main repos and keeps it reasonably current through updates:
sudo dnf install -y kittydnf splits Kitty into four packages. On a server you only SSH into, kitty-terminfo alone is enough (more on that below):
Installing:
kitty x86_64 0:0.47.1-1.fc44 updates 14.9 MiB
Installing dependencies:
kitty-kitten x86_64 0:0.47.1-1.fc44 updates 24.6 MiB
kitty-shell-integration noarch 0:0.47.1-1.fc44 updates 122.8 KiB
kitty-terminfo noarch 0:0.47.1-1.fc44 updates 38.0 KiBThat is Fedora 44. The Fedora 45 Beta repo already carries a newer build. If you are setting up a fresh workstation, the Fedora 44 post-install guide covers the rest of the desktop.
Install Kitty on Arch Linux
Arch had the upstream release packaged the same day it was tagged. Install it with a full system upgrade in the same transaction:
sudo pacman -Syu kittyOn a minimal Arch box this pulls 44 packages. That is an 87 MiB download and 356 MiB on disk, because Mesa and the X11 and Wayland libraries come along. The kitty-terminfo and kitty-shell-integration split packages install automatically. Our pacman cheat sheet covers the -Sy partial upgrade trap if you are tempted to skip -u.
Install Kitty on macOS with Homebrew
Kitty is a Homebrew cask, not a formula. Install it with:
brew install --cask kittyThe shorter brew install kitty works too, because no formula with that name exists. A dry run shows it falling through to the cask:
==> Would install 1 cask:
kittyThe cask requires macOS 12 or later and installs /Applications/kitty.app. A kitty@nightly cask exists too if you want builds from the master branch. Homebrew users who also want a better prompt can pair Kitty with Zsh and Oh My Zsh on macOS.
Install the latest Kitty with the official installer
The upstream installer downloads the prebuilt release and drops it in ~/.local/kitty.app on Linux or /Applications/kitty.app on macOS. It touches nothing else. The launch=n argument stops it from opening a window when it finishes, which matters over SSH:
curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin launch=nThe download is about 44 MB and unpacks to 160 MB. On Debian, install curl and xz-utils first if the image is minimal. On macOS the app it installs is notarized under the Developer ID of Kovid Goyal, so Gatekeeper opens it without complaint.
On Linux, link the binaries into a directory on your PATH and register the desktop entry. These are the upstream commands, run as your normal user:
mkdir -p ~/.local/bin ~/.local/share/applications
ln -sf ~/.local/kitty.app/bin/kitty ~/.local/kitty.app/bin/kitten ~/.local/bin/
cp ~/.local/kitty.app/share/applications/kitty.desktop ~/.local/share/applications/
cp ~/.local/kitty.app/share/applications/kitty-open.desktop ~/.local/share/applications/
sed -i "s|Icon=kitty|Icon=$(readlink -f ~)/.local/kitty.app/share/icons/hicolor/256x256/apps/kitty.png|g" ~/.local/share/applications/kitty*.desktop
sed -i "s|Exec=kitty|Exec=$(readlink -f ~)/.local/kitty.app/bin/kitty|g" ~/.local/share/applications/kitty*.desktop
echo 'kitty.desktop' > ~/.config/xdg-terminals.listDo not copy the kitty binary out of kitty.app. It needs the bundled libraries next to it, which is why upstream tells you to symlink. Ubuntu and Debian add ~/.local/bin to PATH from ~/.profile only if the directory existed at login, so log out and back in once. Then check which Kitty wins:
type -a kittyWith both the apt package and the installer present, the installer copy comes first:
kitty is /home/josphat/.local/bin/kitty
kitty is /usr/bin/kitty
kitty is /bin/kittyLaunching it from the GNOME dock on Ubuntu 26.04 confirms both builds side by side. The window title, prompt and TERM=xterm-kitty are the defaults before any configuration:
To update, rerun the same installer command. To uninstall, delete ~/.local/kitty.app plus the symlinks and desktop files you created. The installer also accepts installer=nightly for nightly builds and installer=version-X.Y.Z to pin a release; check the Kitty releases page for the current tag.
Configure Kitty with kitty.conf
Kitty reads ~/.config/kitty/kitty.conf. Press ctrl+shift+f2 (cmd+, on macOS) inside Kitty and it creates the file with every default commented out, all 3,500 lines of it. Most people want a short file they actually understand instead. Create the directory and open a fresh file:
mkdir -p ~/.config/kitty
vim ~/.config/kitty/kitty.confThis is the exact file we ran on Ubuntu 26.04. It loaded with zero errors on the installer build, the Fedora package and the Debian package:
# Fonts
font_family JetBrains Mono
bold_font auto
italic_font auto
bold_italic_font auto
font_size 12.0
# Window
remember_window_size no
initial_window_width 120c
initial_window_height 34c
window_padding_width 6
confirm_os_window_close 0
# Scrollback and clipboard
scrollback_lines 10000
copy_on_select clipboard
enable_audio_bell no
# Tabs
tab_bar_edge top
tab_bar_style powerline
tab_powerline_style slanted
# Layouts: splits first so new windows split the current one
enabled_layouts splits,stack,tall
map kitty_mod+alt+v launch --location=vsplit --cwd=current
map kitty_mod+alt+h launch --location=hsplit --cwd=current
map kitty_mod+alt+z toggle_layout stack
# Cursor
cursor_shape beam
cursor_blink_interval 0
cursor_trail 3
# Remote control over a local socket only
allow_remote_control socket-only
listen_on unix:/tmp/kittySizes ending in c are cells, so the window opens at 120 columns by 34 rows regardless of font size. kitty_mod defaults to ctrl+shift on Linux and macOS alike. JetBrains Mono comes from the fonts-jetbrains-mono package on Ubuntu and Debian; for icons in prompts, install a patched font from the Nerd Fonts guide and put its name in font_family.
Fully quit Kitty and start it again after creating this file. Two reasons: Kitty only auto-reloads a kitty.conf that existed when it started, and listen_on is never applied by a reload. Recent builds (the Arch, Fedora, Homebrew and installer versions in the table) then pick up later edits automatically. The Ubuntu, Debian and Mint packages are too old for auto-reload, so press ctrl+shift+f5 (ctrl+cmd+, on macOS) after each edit. ctrl+shift+f6 shows the effective settings. A typo does not stop Kitty from starting. It opens an extra window titled “Errors parsing configuration” that names the line, which is how we caught a bad cursor_shape value in the first draft of this file.
On macOS, add these two lines. The first makes Option behave as Alt for shell shortcuts such as alt+b, the second quits Kitty when the last window closes. Restart Kitty afterwards, because a reload does not apply the Option key setting:
macos_option_as_alt yes
macos_quit_when_last_window_closed yesOne config can serve both systems. Put the macOS lines in macos.conf, create an empty linux.conf, and add include ${KITTY_OS}.conf as the last line of kitty.conf. Kitty sets KITTY_OS to linux, macos or bsd when it expands includes, and a later line wins, so keep the include at the bottom.
Change the Kitty theme with kitten themes
Skip hand-copying color values. The themes kitten downloads the kitty-themes collection and previews every theme live in the current window:
kitten themesOur run listed 413 themes, filterable by Dark, Light and Recent. Press / to search and Enter to apply:
For dotfiles and provisioning scripts, pass the theme name and the kitten applies it without the picker:
kitten themes --reload-in=all "Tokyo Night"It writes the colors to current-theme.conf, saves your previous config as kitty.conf.bak, and appends a marked block to the end of kitty.conf:
# BEGIN_KITTY_THEME
# Tokyo Night
include current-theme.conf
# END_KITTY_THEMEIt also comments out any color lines already in kitty.conf so they do not fight the theme. If you keep colors you want to win over the theme, move them into a separate file and include it after that block.
Fonts get the same treatment with kitten choose-fonts, an interactive picker with live previews of regular, bold and italic faces. It writes the result to kitty.conf for you. The Ubuntu 24.04 and Mint package predates it and fails with Error: choose-fonts is not a known subcommand for kitten.
Use tabs, windows and splits
Kitty calls a pane a window and the desktop window an OS window. With the config above, ctrl+shift+alt+v splits the current window side by side and ctrl+shift+alt+h splits it top and bottom, both opening in the same directory. Here is a three-way split with fastfetch, htop and a shell in one tab, with two more tabs on the powerline tab bar:
These are the default shortcuts worth memorizing, checked against the defaults Kitty generates for itself:
| Action | Linux | macOS |
|---|---|---|
| New tab | ctrl+shift+t | cmd+t |
| Close tab | ctrl+shift+q | cmd+w |
| Next / previous tab | ctrl+shift+right / left | shift+cmd+] / [ |
| Set tab title | ctrl+shift+alt+t | shift+cmd+i |
| New window (pane) | ctrl+shift+enter | cmd+enter |
| Close window | ctrl+shift+w | shift+cmd+d |
| Next / previous window | ctrl+shift+] / [ | ctrl+shift+] / [ |
| Resize window | ctrl+shift+r | ctrl+shift+r |
| Next layout | ctrl+shift+l | ctrl+shift+l |
| New OS window | ctrl+shift+n | cmd+n |
| Search scrollback | ctrl+shift+/ | cmd+f |
| Last command output in pager | ctrl+shift+g | ctrl+shift+g |
| Open URL with hints | ctrl+shift+e | ctrl+shift+e |
| Font size up / down / reset | ctrl+shift+= / – / backspace | cmd++ / – / 0 |
| Command palette | ctrl+shift+f3 | ctrl+shift+f3 |
Forget a shortcut and the command palette has it. ctrl+shift+f3 lists every action, grouped by category, with its current binding or “(unmapped)”. Type to filter, Enter to run:
Kitty splits cover most of what people install tmux for on a local machine. On remote servers where sessions must survive a dropped connection, tmux still wins; the tmux cheat sheet has the key bindings.
Use Kitty over SSH with kitten ssh
Shell integration for bash, zsh and fish is on by default. It is what makes ctrl+shift+g show the output of the last command and lets new splits open in the current directory. No rc file edits are needed locally, and the stock Ubuntu ~/.bashrc works with it as shipped.
Remote hosts are a different story. Kitty sets TERM=xterm-kitty, and a server without the Kitty terminfo entry has no idea what that is. Use the SSH kitten instead of plain ssh:
kitten ssh josphat@web02We tested it against a Fedora server with no Kitty packages. On first connect, the kitten copied the terminfo into ~/.terminfo and a 92 KB bootstrap into ~/.local/share/kitty-ssh-kitten, all over the SSH connection itself. The server needs no internet access for that. Full-screen tools work and shell integration follows you to the remote prompt:
[josphat@web02 ~]$ echo $TERM; infocmp xterm-kitty | head -2
xterm-kitty
# Reconstructed via infocmp from file: /home/josphat/.terminfo/./x/xterm-kitty
xterm-kitty|KovIdTTY,The first time you run kitten itself on the remote (for kitten icat or file transfers), the bootstrap downloads the 30 MB kitten binary from GitHub. That one step needs outbound internet. Set remote_kitty no in ~/.config/kitty/ssh.conf to skip it. Add alias ssh="kitten ssh" to your shell rc file if you want the kitten everywhere.
Display images in the terminal with kitten icat
The Kitty graphics protocol draws real pixels, not block characters. The icat kitten uses it:
kitten icat --place 90x22@0x2 /usr/share/backgrounds/Resolute_Raccoon_Wallpaper_Dimmed_3840x2160.pngThe --place value is columns x rows @ left x top, measured in cells. Without it, icat shrinks images wider than the window to fit and leaves smaller ones at their native size. kitten icat --clear removes it again:
Terminal file managers such as yazi use the same protocol for image previews, so they show real thumbnails inside Kitty.
Control Kitty from scripts
With allow_remote_control socket-only and listen_on set, kitten @ drives a running Kitty from any shell: open tabs, split windows, send keystrokes, read text back. The screenshots in this guide were staged that way. Inside a Kitty window, no extra flags are needed because Kitty exports the socket path:
kitten @ launch --type=tab --tab-title logs --cwd=current
kitten @ launch --location=vsplit --cwd=current htop
kitten @ ls | jq -r '.[].tabs[].layout'The catch is the socket name. Kitty appends its PID to the path in listen_on, so unix:/tmp/kitty becomes /tmp/kitty-9569. Each window gets the real path in its environment:
env | grep -E '^(KITTY_LISTEN_ON|KITTY_PID|KITTY_WINDOW_ID|TERM)='The output from one of our windows:
KITTY_LISTEN_ON=unix:/tmp/kitty-9569
KITTY_PID=9569
KITTY_WINDOW_ID=4
TERM=xterm-kittyFrom outside Kitty, such as a cron job or a script started over SSH, pass the real path with --to unix:/tmp/kitty-9569. Keep socket-only rather than yes: with yes, any program printing escape codes into the terminal can issue remote control commands. The socket is not a sandbox either. Any local process that can open it can read window text and send keystrokes, so do not enable this on a shared login host.
Make Kitty the default terminal
GNOME on Ubuntu 26.04 resolves its default terminal through xdg-terminal-exec. It checks ~/.config/ubuntu-xdg-terminals.list before the generic xdg-terminals.list the installer steps wrote. When the Ubuntu file named Ptyxis on our VM, Ptyxis won over Kitty. Write Kitty into the Ubuntu-specific list:
echo 'kitty.desktop' > ~/.config/ubuntu-xdg-terminals.listAfter that, ctrl+alt+t opened a new Kitty window on the GNOME desktop. Ubuntu 24.04 and Debian use the alternatives system instead. The apt package registers /usr/bin/kitty as an x-terminal-emulator candidate, and an installer build needs registering by hand first:
sudo update-alternatives --install /usr/bin/x-terminal-emulator x-terminal-emulator "$HOME/.local/kitty.app/bin/kitty" 50
sudo update-alternatives --config x-terminal-emulatorCinnamon on Linux Mint launches the terminal shortcut from its own setting, which defaulted to gnome-terminal on our VM. Setting it made ctrl+alt+t open Kitty on our Mint VM. Use the full path for the installer build, or plain kitty for the apt package:
gsettings set org.cinnamon.desktop.default-applications.terminal exec "$HOME/.local/kitty.app/bin/kitty"On macOS there is no system default terminal setting. Keep Kitty in the Dock, or bind a global hotkey with a launcher such as Raycast.
Kitty errors we hit and how to fix them
Every message below was captured on the lab machines, word for word.
‘xterm-kitty’: unknown terminal type.
This appears when you SSH from Kitty with plain ssh into a host that lacks the terminfo entry. clear fails with that message, tput reports unknown terminal "xterm-kitty", and editors draw garbage. Use kitten ssh. When you have to use plain ssh (scripts, or a client that is not Kitty), push the entry once:
infocmp -a xterm-kitty | ssh web01 tic -x -o \~/.terminfo /dev/stdintic warns that “older tic versions may treat the description field as an alias” and installs the entry anyway. The next interactive session on Ubuntu 24.04 found it in ~/.terminfo/x/xterm-kitty and tput cols worked. Installing the kitty-terminfo package on the server fixes it for every user.
Errors parsing configuration: Invalid cursor shape
Kitty opened a second window with this text when our first config used a blink setting as a shape:
In file /home/josphat/.config/kitty/kitty.conf:
32:Invalid cursor shape: blink_off allowed values are block, beam, underline in line: cursor_shape blink_offThe fix is cursor_shape beam plus cursor_blink_interval 0 to stop the blink. The same window reports any misspelled option, so read it rather than closing it.
Ignoring unknown config key: cursor_trail
The Ubuntu 24.04 and Mint package (0.32.2) logs this for our config, because the cursor trail option arrived in a later release. It’s a warning, not an error, and the rest of the file applies. Every other option in the config above loaded on that build, so the file is safe to share across machines. Remove the line or install the upstream build if you want the effect.
Error: Failed to connect to unix:/tmp/kitty
The full message was Error: Failed to connect to unix:/tmp/kitty with error: dial unix /tmp/kitty: connect: no such file or directory. Remote control is working; the path is wrong because of the PID suffix covered above. List the real socket with ls /tmp/kitty-*, or read $KITTY_LISTEN_ON from inside a Kitty window.
Kitty prints libEGL or MESA warnings in a VM
Inside a VM without GPU passthrough, Kitty logs lines such as libEGL warning: egl: failed to create dri2 screen and MESA: error: ZINK: failed to choose pdev when started from a shell, then falls back to the Mesa software renderer and runs normally. On real hardware these do not appear. If Kitty refuses to start at all and prints OpenGL version is X.Y, version >= 3.1 required for kitty, the driver is too old. Kitty needs OpenGL 3.1 on Linux and 3.3 on macOS.
