Kitty.conf Basics
The ~/.config/kitty/kitty.conf file is the main configuration file for kitty. It controls everything from fonts and colors to key bindings and window layout.
Learning Focus
Start with a minimal, well-understood config file. Add complexity only when you know what each line does. Reload frequently to test changes.
Where the Config Lives
# Personal config (per user)
~/.config/kitty/kitty.conf
# Generate the default commented config
kitty +runpy 'from kitty.config import *; print(commented_out_default_config())' > ~/.config/kitty/kitty.conf
# Verify the location kitty uses
kitty --config 2>&1 || echo "kitty reads ~/.config/kitty/kitty.conf by default"
Reloading Config
# from inside kitty
Ctrl+Shift+F5
# from the command line
kitty @ load-config
# from the command palette
Ctrl+Shift+p → type "load" → select "load config file"
note
Unlike tmux, kitty does not auto-reload on file change. You must explicitly trigger a reload.
Starter Configuration
This is a production-ready baseline kitty.conf:
~/.config/kitty/kitty.conf
# ===========================
# Fonts
# ===========================
font_family JetBrains Mono
font_size 12.0
font_features JetBrains-Mono +liga +calt
# ===========================
# Cursor
# ===========================
cursor_shape beam
cursor_blink_interval 0.5
# ===========================
# Scrollback
# ===========================
scrollback_lines 10000
scrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS
# ===========================
# Colors (Catppuccin Mocha)
# ===========================
foreground #cdd6f4
background #1e1e2e
# Black
color0 #45475a
color8 #585b70
# Red
color1 #f38ba8
color9 #f38ba8
# Green
color2 #a6e3a1
color10 #a6e3a1
# Yellow
color3 #f9e2af
color11 #f9e2af
# Blue
color4 #89b4fa
color12 #89b4fa
# Magenta
color5 #cba6f7
color13 #cba6f7
# Cyan
color6 #94e2d5
color14 #94e2d5
# White
color7 #bac2de
color15 #a6adc8
selection_foreground #1e1e2e
selection_background #f5e0dc
# ===========================
# Window / Tab Bar
# ===========================
window_padding_width 4
tab_bar_style powerline
active_tab_foreground #1e1e2e
active_tab_background #89b4fa
inactive_tab_foreground #bac2de
inactive_tab_background #313244
# ===========================
# Mouse
# ===========================
mouse_hide_wait 2.0
select_by_word_characters :@-./_~?&=%+#
# ===========================
# Performance
# ===========================
sync_to_monitor no
repaint_delay 10
input_delay 3
Configuration Option Categories
Font and Text Options
font_family JetBrains Mono
font_size 12.0
font_features JetBrains-Mono +liga
adjust_line_height 0
adjust_column_width 0
disable_ligatures never
Appearance Options
background_opacity 0.95
background_blur 8
window_padding_width 4
window_margin_width 0
hide_window_decorations no
Cursor Options
cursor_shape beam # block, beam, underline
cursor_blink_interval 0.5 # seconds, 0 to disable
cursor_stop_blinking_after 15.0 # seconds of inactivity
Scrollback Options
scrollback_lines 10000
scrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS
scrollback_indicator_opacity 0.75
Live Reload Workflow
# edit your config
vim ~/.config/kitty/kitty.conf
# reload without closing anything
kitty @ load-config
# verify no errors in the log
kitty @ ls | grep -i error
Checking Current Options
# dump all current kitty settings
kitty @ get-config
# check a specific setting
kitty @ get-config font_size
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
| Config syntax error | Kitty ignores the line or crashes | Check with kitty @ load-config — it reports the line number |
| Forgetting to reload | Changes not applied | Run kitty @ load-config or Ctrl+Shift+F5 |
| Wrong font name listed | Font falls back to monospace | Use kitty --debug-fonts to list available fonts |
| Missing quotes on values with spaces | Config parse error | Wrap values in double quotes: font_family "JetBrains Mono" |
| Typo in color name | Default color used | Use hex values (#rrggbb) instead of names |
Hands-On Practice
# create your config directory
mkdir -p ~/.config/kitty
# dump the default commented config
kitty +runpy 'from kitty.config import *; print(commented_out_default_config())' > ~/.config/kitty/kitty.conf
# test reload
kitty @ load-config
# check a specific setting
kitty @ get-config font_size
# edit and reload cycle
echo "font_size 14.0" >> ~/.config/kitty/kitty.conf
kitty @ load-config
kitty @ get-config font_size