Kitty.conf Reference
The ~/.config/kitty/kitty.conf file controls every aspect of kitty's behavior. This reference groups all options by category with defaults and descriptions.
Learning Focus
Use this as a lookup reference. You don't need to memorize options — bookmark this page and search it when you need a specific setting.
Font Settings
| Setting | Default | Description |
|---|---|---|
font_family | monospace | Primary font family |
bold_font | auto | Font for bold text (auto = derived from font_family) |
italic_font | auto | Font for italic text |
bold_italic_font | auto | Font for bold-italic text |
font_size | 11.0 | Font size in points |
font_features | none | OpenType feature tags (e.g., FiraCode +zero +cv01) |
disable_ligatures | never | Disable ligatures: never, always, cursor |
adjust_line_height | 0 | Extra line height in points (positive = taller) |
adjust_column_width | 0 | Extra column width in points |
font_family_monospace | none | Font used when $LANG Unicode width differs |
symbol_map | none | Map Unicode codepoints to specific fonts |
force_ltr | no | Force left-to-right text direction |
narrow_symbols | none | Treat specific Unicode chars as narrow |
Cursor Settings
| Setting | Default | Description |
|---|---|---|
cursor_shape | block | Cursor shape: block, beam, underline |
cursor_blink_interval | -1 | Blink interval in ms (-1 = no blink, 0 = system default) |
cursor_stop_at_powerline | no | Stop cursor at powerline glyphs (avoid visual gap) |
cursor_trail | 0 | Cursor trail length (0 = off, 1-3 are reasonable) |
cursor_beam_thickness | 1.5 | Thickness of beam cursor in points |
cursor_underline_thickness | 2.0 | Thickness of underline cursor in points |
cursor_shape_unfocused | underline | Cursor shape when window is unfocused |
Scrollback Settings
| Setting | Default | Description |
|---|---|---|
scrollback_lines | 10000 | Number of lines kept in scrollback buffer |
scrollback_indicator_opacity | 0.0 | Opacity of scrollback indicator (0-1, 0 = hidden) |
scrollback_pager_history_size | 5 | Number of history lines shown in pager |
scrollback_fill_enlarged_window | no | Fill new window area with scrollback content |
Mouse Settings
| Setting | Default | Description |
|---|---|---|
mouse_hide_wait | 2.0 | Seconds before hiding mouse cursor (-1 = never hide) |
url_color | #0087bd | Color for underlined URLs |
url_style | curly | URL underline style: none, single, double, curly |
url_prefixes | ftp ssh git http https rsync | Protocols detected as clickable URLs |
open_url_with | default | Command to open URLs (default = xdg-open) |
click_interval | -1.0 | Double-click interval (-1 = system default) |
focus_follows_mouse | no | Window focus follows mouse movement |
pointer_shape_when_grabbed | arrow | Cursor shape when pointer is grabbed |
Performance Settings
| Setting | Default | Description |
|---|---|---|
repaint_delay | 10 | Min delay between screen repaints (ms, lower = smoother) |
input_delay | 3 | Min delay between input event processing (ms) |
sync_to_busy | yes | Sync rendering to application output rate |
repaint_defer_delay | 5 | Delay after input before repaint (ms) |
flush_when_urgent_input | yes | Repaint immediately on urgent (bell) input |
fullscreen_new_window | no | Create new windows in fullscreen mode |
confirm_os_window_close | 0 | Prompt on close: 0 = no, 1 = always, 2 = if multiple windows |
Bell Settings
| Setting | Default | Description |
|---|---|---|
visual_bell_duration | 0.0 | Duration of visual bell flash (seconds, 0 = off) |
enable_audio_bell | yes | Enable system bell sound |
bell_on_tab | 🔔 | Text/label shown on tab when bell occurs |
visual_bell_color | none | Color for visual bell flash |
window_alert_on_bell | yes | Flash taskbar/dock on bell |
urgent_on_bell | yes | Mark window as urgent on bell |
Window Settings
| Setting | Default | Description |
|---|---|---|
background_opacity | 1.0 | Window background opacity (0.0-1.0, requires compositor) |
background_blur | 0 | Background blur radius (requires compositor with blur) |
window_padding_width | 0 | Internal padding in pixels (number or NxM) |
window_margin_width | 0 | External margin in pixels (number or NxM) |
placement_strategy | center | Window placement: center, top-left, top-right, etc. |
remember_window_size | yes | Remember and restore window size |
initial_window_width | 640 | Initial window width in pixels |
initial_window_height | 400 | Initial window height in pixels |
hide_window_decorations | no | Hide title bar (requires WM with CSD support) |
resize_debounce_time | 0.1 | Delay before resizing after window resize (seconds) |
resize_in_steps | no | Resize in cell-size steps only |
window_border_width | 0.0 | Active window border width in points |
Tab Bar Settings
| Setting | Default | Description |
|---|---|---|
tab_bar_style | powerline | Tab bar style: hidden, powerline, slanted, separator, custom |
tab_bar_edge | top | Tab bar position: top or bottom |
tab_bar_min_tabs | 2 | Minimum tabs before bar appears |
tab_separator | ┃ | Separator between tabs (if tab_bar_style = separator) |
tab_activity_symbol | none | Symbol shown on tabs with activity |
active_tab_foreground | #000 | Active tab text color |
active_tab_background | #eee | Active tab background color |
inactive_tab_foreground | #444 | Inactive tab text color |
inactive_tab_background | #999 | Inactive tab background color |
tab_bar_margin_width | 0.0 | Margin around tab bar |
Colors
| Setting | Default | Description |
|---|---|---|
foreground | #dddddd | Default text color |
background | #000000 | Default background color |
selection_foreground | #000000 | Selected text color |
selection_background | #fffacd | Selection highlight color |
color0 through color15 | ANSI palette | Standard 16 ANSI terminal colors |
color16 through color255 | Extended palette | Extended 256-color palette |
mark1_foreground | #000 | First highlight color (e.g., search match) |
mark1_background | #98d8c8 | First highlight background |
mark2_foreground | #000 | Second highlight color |
mark2_background | #f4d03f | Second highlight background |
mark3_foreground | #000 | Third highlight color |
mark3_background | #e74c3c | Third highlight background |
url_color | #0087bd | URL highlight color |
Advanced Settings
| Setting | Default | Description |
|---|---|---|
shell | . (login shell) | Program to run inside kitty windows |
term | xterm-kitty | Value of $TERM environment variable |
env | none | Additional environment variables (ENV_NAME VALUE) |
clipboard_control | write-clipboard clipboard | Clipboard access: read-clipboard, write-clipboard, etc. |
allow_remote_control | no | Enable remote control: no, yes, socket-only, password |
listen_on | none | Remote control socket path |
strip_trailing_spaces | smart | Strip trailing spaces on paste: never, smart, always |
input_delay | 3 | Min delay between input processing (ms) |
kitty_mod | ctrl+shift | Modifier key prefix for shortcuts |
clear_all_shortcuts | no | Remove all default shortcuts (for fully custom mapping) |
file_transfer_confirmation | always | Confirmation for file transfers: always, never, large |
sync_protocol | no | Enable synchronized update protocol |
copy_on_select | no | Auto-copy selection to clipboard |
Deprecated / Removed
| Setting | Replacement | Notes |
|---|---|---|
cursor_color | — | Use color0/color1 or shell-level cursor control |
cursor_text_color | — | Cursor text color depends on background contrast |
dynamic_background_opacity | background_opacity | Renamed in kitty 0.20 |
font_family_emoji | symbol_map | Use symbol_map to map emoji codepoints |
Complete Config Validation
# Check your whole config for errors
kitty --debug-config 2>&1
# See effective settings (including defaults)
kitty @ get-colors
# Dump all options with current values
grep -v "^#" ~/.config/kitty/kitty.conf | grep -v "^$" | head -100
# Check a specific setting
grep "^background_opacity" ~/.config/kitty/kitty.conf
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
| Syntax error (missing space) | Setting ignored silently | Use format: setting value (space separated) |
| Wrong value type | Kitty falls back to default | Check types: numbers, strings, colors (#rrggbb) |
background_opacity has no effect | No compositor running | Install picom (X11) or use Wayland with native blur |
kitty_mod not working | Shortcuts use old prefix | Change kitty_mod before any other key mapping |
| Color names instead of hex | Color not applied | Always use hex format: #rrggbb |
allow_remote_control not set | kitty @ commands fail | Restart kitty after setting allow_remote_control yes |
| Tab bar not visible | tab_bar_style hidden | Set tab_bar_style powerline or tab_bar_style slanted |
Hands-On Practice
# 1. View your complete effective config
kitty @ get-colors
grep -v "^#" ~/.config/kitty/kitty.conf | grep -v "^$"
# 2. Validate your config
kitty --debug-config 2>&1
# 3. Test a temporary setting change
echo "background_opacity 0.8" >> ~/.config/kitty/kitty.conf
kitty @ load-config
# Remove it if you don't want it permanently
# 4. Create a minimal working config
cat > /tmp/minimal-kitty.conf << 'EOF'
font_family monospace
font_size 12
cursor_shape beam
scrollback_lines 5000
tab_bar_style powerline
EOF
# Test it
kitty --config /tmp/minimal-kitty.conf &