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.

⚠️ Ghostty 1.2.0 Breaking Changes Version 1.2.0 introduced significant breaking changes. Theme names changed from kebab-case to Title Case (e.g., catppuccin-mocha → Catppuccin Mocha), keyboard handling was overhauled, and font ligatures are now disabled by default. See the updated sections below for the new configuration format.

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.

🔴 Theme Name Changes in 1.2.0 Theme names changed from kebab-case to Title Case with spaces. Use quotes when theme names contain spaces. Run ghostty +list-themes to see the exact names.

# automatic light/dark theme switching (1.2.0 format)
theme = "light:Catppuccin Latte,dark:Catppuccin Mocha"

# or single theme
theme = "TokyoNight"

popular themes (1.2.0 naming):

• "Catppuccin Mocha" / "Catppuccin Frappe" - modern pastel themes
• "TokyoNight" / "TokyoNight 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

scrollbar configuration

⚠️ Experimental Feature - Requires Development Build GTK scrollbar support was merged on October 17, 2025 via PR #9245. This feature is not yet in a stable release - it only exists in the main branch development builds. For complete setup instructions, see the dedicated scrollbar guide.

control when scrollbars appear for navigating the scrollback buffer:

scrollbar = system   # default - follows GTK system settings

valid options:

• system (default): respects GTK system scrollbar preferences, typically showing scrollbars while actively scrolling or hovering over the gutter
• never: hides scrollbars completely while still allowing mouse wheel scrolling, keyboard navigation, and keybind actions

📌 Build Requirements To use GTK scrollbars, you need to build from the main branch after October 17, 2025. See the scrollbar setup guide for detailed instructions.

scrollbar behavior

the scrollbar appears on the right side of the terminal and provides:

• visual position indicator: shows your current location in the scrollback buffer
• mouse interaction: click and drag to jump through history
• smooth scrolling: integrates with GTK’s native smooth scrolling
• theme integration: automatically matches your GTK theme colors and styling

system integration

when set to system, scrollbar visibility follows your desktop environment’s global preferences:

• gnome: controlled by “Show scrollbars” setting in gnome tweaks
• kde plasma: follows system settings → appearance → application style
• gtk settings: can be configured via gsettings set org.gnome.desktop.interface overlay-scrolling

performance notes

scrollbars have minimal performance impact. if you prefer a completely minimal interface or use keyboard/mouse-only scrolling, set to never:

scrollbar = never

you can still scroll using:

• ctrl+shift+up/down for prompt jumping (requires shell integration)
• mouse wheel for smooth scrolling
• page up/page down for page-based navigation
• custom keybindings for scrollback actions

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:

⚠️ Keyboard Changes in 1.2.0 The physical: prefix for keybindings has been removed. Single characters now match based on keyboard layout, while multi-character key names match physical keys. Also, avoid binding ctrl+l as it conflicts with clear screen in SSH/byobu sessions.

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 (ctrl+shift+k removed to avoid conflict with clear_screen)
keybind = ctrl+shift+h=goto_split:left
keybind = ctrl+shift+j=goto_split:bottom
keybind = ctrl+shift+l=goto_split:right
# Note: Use Alt+Up for top split navigation instead

# 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

# Note: Ctrl+1-9 bindings removed to preserve standard terminal behavior
# Use Ctrl+Tab/Ctrl+Shift+Tab for tab navigation instead

# 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
font-feature = +dlig  # discretionary ligatures (disabled by default in 1.2.0)

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

font features explained

ℹ️ Font Ligature Changes in 1.2.0 The +dlig (discretionary ligatures) feature is now disabled by default. If your ligatures stopped working after upgrading, explicitly enable it with font-feature = +dlig.

• ligatures (+liga): combine character sequences like =>, !=, -> into single glyphs
• contextual alternatives (+calt): adjust character appearance based on context
• discretionary ligatures (+dlig): additional optional ligatures (disabled by default in 1.2.0)
• 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
• 1.2.0 (current stable): theme name changes, keyboard overhaul, font ligature defaults
• main branch only (post-1.2.0): gtk scrollbar support (PR #9245, oct 17, 2025)

complete configuration

download the complete configuration file tested on ubuntu 25.10 with ghostty 1.2.0.

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
• set as default terminal
• github repository

next steps

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