Skip to main content

Terminfo Management

Kitty uses its own terminfo entry (xterm-kitty) to advertise advanced capabilities — true color, inline images, clipboard control, and protocol extensions. The terminfo must exist on any remote host you connect to via SSH.

Learning Focus

Terminfo mismatch is the #1 source of "kitty doesn't look right on remote" issues. Learn to install it automatically and verify it manually.

What is Terminfo?​

Terminfo is a database that describes terminal capabilities — what escape sequences a terminal supports. Programs like vim, htop, and less read terminfo to decide how to render:

Application
    │
    ▼
Reads $TERM environment variable
    │
    ▼
Looks up /usr/share/terminfo/x/xterm-kitty
    │
    ▼
Discovers capabilities:
  ├── true color (Tc)
  ├── 256 colors (colors#256)
  ├── kitty protocol (kitten)
  └── inline images (Ic)
    │
    ▼
Renders output using supported escape sequences

Without the correct terminfo, the remote host falls back to a generic terminal like xterm-256color, and kitty-specific features are lost.

How Kitty Installs Terminfo Automatically​

When you use kitty +kitten ssh, the kitten checks the remote host's terminfo:

# Automatic: Let kitty handle it
kitty +kitten ssh user@server

# Force-install terminfo on remote (even if already present)
kitty +kitten ssh --install-terminal user@server

# Skip terminfo check (if you already installed it)
kitty +kitten ssh --no-install-terminal user@server

During connection, you may see:

┌─────────────────────────────────────────────┐
│ The terminal terminfo file xterm-kitty is   │
│ not present on the remote server.           │
│                                             │
│ Install it now? [Y/n]                       │
└─────────────────────────────────────────────┘

Type Y (or press Enter) to install it automatically. This runs tic on the remote to compile the terminfo entry.

Manual Terminfo Installation​

Sometimes you need to install terminfo manually — for automation, restricted environments, or non-standard SSH ports:

Method 1: Using kitty +kitten ssh --install-terminal​

# One-line install
kitty +kitten ssh --install-terminal user@server

Method 2: Manual Copy via infocmp and ssh​

# Step 1: Export local terminfo to a file
infocmp -x xterm-kitty > /tmp/xterm-kitty.info

# Step 2: Copy to remote and compile
scp /tmp/xterm-kitty.info user@server:/tmp/
ssh user@server "tic -x /tmp/xterm-kitty.info"

# Clean up
ssh user@server "rm /tmp/xterm-kitty.info"

Method 3: One-Liner (Pipe)​

# Export and install in one command
infocmp -x xterm-kitty | ssh user@server "tic -x -"
note

The -x flag is critical — it preserves non-standard capabilities that kitty defines beyond the standard terminfo database.

Checking Terminfo is Correct​

# On the remote host, check:
echo $TERM
# Expected: xterm-kitty

# Verify the terminfo entry exists
infocmp -x xterm-kitty > /dev/null 2>&1 && echo "OK" || echo "MISSING"

# List terminfo capabilities
infocmp -x xterm-kitty | grep -E "(colors|pairs|kitten|ICap)"

# Check if true color is advertised
infocmp -x xterm-kitty | grep "Tc"
# Should output something like: Tc, \

# Verify 256 colors
tput colors
# Should output: 256

# Test with a known kitty feature:
printf '\e[38:2:255:100:50mHello\e[m\n'
# Should show orange-ish text (true color)

Common Terminfo Scenarios​

Scenario A: No Terminfo Installed​

$ ssh user@server
$ echo $TERM
xterm-256color          ← kitty features disabled
$ infocmp xterm-kitty
infocmp: couldn't open terminfo file xterm-kitty.

Fix: Run kitty +kitten ssh --install-terminal user@server

Scenario B: Wrong TERM Set​

$ ssh user@server
$ echo $TERM
xterm                  ← old terminal, limited colors

Fix: Set TERM=xterm-kitty manually after connecting, or configure SSH to forward it.

Scenario C: Partial Installation (Missing -x)​

$ infocmp xterm-kitty | grep -c "kitten"
0                      ← kitty-specific caps missing

Fix: Reinstall with tic -x (include extended capabilities).

Automating via SSH Config​

~/.ssh/config
Host *
  # Forward TERM to remote
  SetEnv TERM=xterm-kitty

Host server*
  # Auto-fix terminfo on first connect
  RemoteCommand kitty +kitten ssh --install-terminal %h

Common Pitfalls​

PitfallSymptomFix
Terminfo not installed on remoteTERM=xterm-256colorRun kitty +kitten ssh --install-terminal
Missing -x flag during ticKitty features missingReinstall with tic -x to preserve extended caps
SSH SendEnv blocks custom TERMTERM forced to genericAdd SetEnv TERM=xterm-kitty to ~/.ssh/config
infocmp not found locallyCan't export terminfoInstall ncurses-term or ncurses-bin package
Debian/Ubuntu missing terminfotic not available on remoteInstall ncurses-term on the remote server

Hands-On Practice​

# 1) Export your local kitty terminfo
infocmp -x xterm-kitty > /tmp/kitty-terminfo.txt
echo "Local terminfo exported to /tmp/kitty-terminfo.txt"
wc -l /tmp/kitty-terminfo.txt

# 2) Check local kitty features
infocmp -x xterm-kitty | grep -oP '(?<=, )[A-Z][a-z]+' | head -20
echo "---"
infocmp -x xterm-kitty | grep -c "kitten"
echo "kitten capabilities found"

# 3) Simulate remote installation (to localhost)
infocmp -x xterm-kitty | ssh localhost "tic -x -"
echo "Terminfo installed on localhost"

# 4) Verify on localhost
ssh localhost "echo TERM=\$TERM; tput colors; infocmp -x xterm-kitty > /dev/null 2>&1 && echo 'OK' || echo 'MISSING'"

# 5) Clean up
rm /tmp/kitty-terminfo.txt

What's Next​