ghostty terminal configuration

battle-tested ghostty configuration optimized for productivity, performance, and aesthetics on linux systems.

overview

ghostty ships with excellent defaults, but customization unlocks its full potential. this configuration provides:

• modern glassmorphic appearance with transparency and blur
• catppuccin theme with automatic light/dark switching
• optimized performance using gtk single instance mode
• productive keybindings for splits, tabs, and navigation
• enhanced security with clipboard protection
• shell integration for smart features like prompt jumping

download the complete config file or copy individual sections below.

prerequisites

ensure ghostty is installed following the ubuntu build guide or from official packages for your distribution.

configuration location

ghostty looks for configuration at:

~/.config/ghostty/config

create the directory if it doesn’t exist:

mkdir -p ~/.config/ghostty

theme & appearance

color schemes

ghostty includes 300+ built-in themes from the iterm2 color schemes collection.

# automatic light/dark theme switching
theme = dark:catppuccin-mocha,light:catppuccin-latte

# or single theme
theme = tokyo-night

popular themes:

• catppuccin-mocha / catppuccin-frappe - modern pastel themes
• tokyo-night / tokyo-night-storm - vibrant city-inspired
• dracula - classic dark purple theme
• gruvbox-dark / gruvbox-light - retro warm colors
• nord - arctic-inspired blues

transparency & blur

create a modern glassmorphic effect that maintains readability:

background-opacity = 0.95   # 95% opaque
background-blur = 10        # frosted glass effect

the blur radius (1-20) determines the frosting intensity. higher values create stronger blur but may impact performance on older gpus.

window padding

breathing room improves readability and aesthetics:

window-padding-x = 16
window-padding-y = 16
window-padding-balance = true   # centers text when window doesn't match cell grid
window-padding-color = background

performance optimizations

gtk single instance mode

crucial for linux performance - dramatically reduces startup time and memory usage:

gtk-single-instance = desktop

single instance mode ensures subsequent windows open in the existing process rather than spawning new ones. typical improvements:

• startup time: 500ms → 50ms
• memory usage: 50mb per window → 5mb per window

scrollback buffer

balance between history retention and memory usage:

scrollback-limit = 100000000  # ~100mb per terminal

each byte stores one character of history. adjust based on your workflow:

• minimal (1mb): 1000000 - for resource-constrained systems
• standard (10mb): 10000000 - good for most users
• extensive (100mb): 100000000 - for heavy log analysis

linux cgroups

control resource usage per terminal instance:

linux-cgroup = single-instance
linux-cgroup-memory-limit = 2147483648  # 2gb max
linux-cgroup-processes-limit = 1000

shell integration

shell integration is ghostty’s killer feature, automatically injected for bash, zsh, fish, and elvish:

shell-integration = detect
shell-integration-features = cursor,sudo,title

enabled features:

• working directory inheritance: new tabs/splits start in the same directory
• prompt marking: jump between prompts with ctrl+shift+up/down
• smart close confirmation: no confirmation when at a prompt
• cursor styling: bar cursor at prompts for visibility
• sudo awareness: preserves context through sudo
• dynamic titles: accurate window titles

prompt jumping

navigate command history efficiently:

keybind = ctrl+shift+up=jump_to_prompt:-1    # previous prompt
keybind = ctrl+shift+down=jump_to_prompt:1   # next prompt

productive keybindings

keybindings follow the pattern trigger=action:parameter:

splits & panes

create and navigate terminal panes:

# create splits
keybind = ctrl+shift+enter=new_split:right
keybind = ctrl+shift+d=new_split:down

# navigate with vim keys
keybind = ctrl+shift+h=goto_split:left
keybind = ctrl+shift+j=goto_split:bottom
keybind = ctrl+shift+k=goto_split:top
keybind = ctrl+shift+l=goto_split:right

# or arrow keys
keybind = alt+left=goto_split:left
keybind = alt+right=goto_split:right
keybind = alt+up=goto_split:top
keybind = alt+down=goto_split:bottom

# split management
keybind = ctrl+shift+z=toggle_split_zoom   # maximize current split
keybind = ctrl+shift+equal=equalize_splits # balance split sizes

tabs

efficient tab management:

# tab creation/navigation
keybind = ctrl+shift+t=new_tab
keybind = ctrl+tab=next_tab
keybind = ctrl+shift+tab=previous_tab

# direct tab access
keybind = ctrl+1=goto_tab:1
keybind = ctrl+2=goto_tab:2
# ... through ctrl+9

# tab movement
keybind = ctrl+shift+alt+left=move_tab:-1
keybind = ctrl+shift+alt+right=move_tab:1

font adjustment

quick font size changes without editing config:

keybind = ctrl+plus=increase_font_size:1
keybind = ctrl+minus=decrease_font_size:1
keybind = ctrl+0=reset_font_size

security & clipboard

ghostty takes security seriously:

# clipboard protection
clipboard-read = ask              # prompts before programs read clipboard
clipboard-write = allow           # allows writing to clipboard
clipboard-paste-protection = true # warns about dangerous pastes (e.g., commands with newlines)
copy-on-select = true            # auto-copy selection

# prevent title query attacks
title-report = false

clipboard protection detects potentially dangerous pastes:

• commands containing newlines that would auto-execute
• hidden control characters
• suspicious command patterns

font configuration

ghostty includes jetbrains mono by default:

font-family = JetBrains Mono
font-size = 11

# programming ligatures
font-feature = +liga  # transforms => != etc into single glyphs
font-feature = +calt  # contextual alternatives

# fallback fonts for better unicode
font-family = Noto Color Emoji
font-family = Noto Sans CJK JP

font features explained

• ligatures (+liga): combine character sequences like =>, !=, -> into single glyphs
• contextual alternatives (+calt): adjust character appearance based on context
• stylistic sets (+ss01 through +ss20): alternative character designs

advanced features

quick terminal (dropdown)

configure a quake-style dropdown terminal:

quick-terminal-position = top
quick-terminal-screen = main
quick-terminal-animation-duration = 0.2
quick-terminal-autohide = true

# bind to grave key (backtick)
keybind = ctrl+grave=toggle_quick_terminal

custom shaders

apply visual effects with glsl shaders:

custom-shader = /path/to/shader.glsl
custom-shader-animation = true

popular effects:

• crt scanlines
• retro phosphor glow
• subtle animations

troubleshooting

wayland vs x11

force specific backend if experiencing issues:

# force x11
GDK_BACKEND=x11 ghostty

# force wayland
GDK_BACKEND=wayland ghostty

font rendering issues

adjust freetype flags:

freetype-load-flags = no-hinting

options: default, no-hinting, no-autohint, force-autohint, no-bitmap

performance problems

disable features progressively:

# disable blur
background-blur = 0

# disable transparency
background-opacity = 1.0

# disable single instance
gtk-single-instance = false

# reduce scrollback
scrollback-limit = 1000000

configuration management

reload configuration

apply changes without restarting:

# keybind
ctrl+shift+,

# or via cli
ghostty reload

split configuration

organize complex configurations:

# ~/.config/ghostty/config
config-file = themes.conf
config-file = keybinds.conf
config-file = ?local.conf  # optional file (? prefix)

version-specific features

check your ghostty version for feature availability:

ghostty --version

features added in recent versions:

• 1.1.0: quick terminal, custom shaders
• 1.1.2: improved shell integration
• 1.1.4: gtk4 layer shell support

complete configuration

download the complete configuration file tested on ubuntu 25.04 with ghostty 1.1.4.

key highlights:

• catppuccin theme with auto light/dark switching
• optimized for 2k/4k displays
• comprehensive keybindings for productivity
• security-conscious defaults
• performance tuned for modern linux

resources

• official documentation
• configuration reference
• keybinding guide
• theme gallery
• ubuntu build guide
• github repository

next steps

1. install ghostty using the build guide
2. download the config from here
3. customize theme and keybindings to your preferences
4. explore advanced features like splits and shell integration
5. contribute your configuration improvements back to the community