Ghostty Configuration

Guidance for configuring the Ghostty terminal emulator. Ghostty uses text-based config files with sensible defaults and zero required configuration.

Config File Locations

XDG Path (All Platforms):

$XDG_CONFIG_HOME/ghostty/config
Defaults to ~/.config/ghostty/config if XDG_CONFIG_HOME undefined

macOS Additional Path:

~/Library/Application Support/com.mitchellh.ghostty/config
If both XDG and macOS paths exist, both are loaded with macOS path taking precedence

Config Syntax

# Comments start with #
background = 282c34
foreground = ffffff
font-family = "JetBrains Mono"
keybind = ctrl+z=close_surface
font-family =                     # Empty value resets to default

Rules:

Keys are case-sensitive (use lowercase)
Whitespace around = is flexible
Values can be quoted or unquoted
Empty values reset to defaults
Every config key works as CLI flag: ghostty --background=282c34

Config Loading & Includes

Files processed sequentially - later entries override earlier ones.

# Include additional configs
config-file = themes/dark.conf
config-file = ?local.conf       # ? prefix = optional (no error if missing)

Critical: config-file directives are processed at the file's end. Keys appearing after config-file won't override the included file's values.

Runtime Reloading

Linux: ctrl+shift+,
macOS: cmd+shift+,

Some options cannot be reloaded at runtime. Some apply only to newly created terminals.

CLI Commands

Ghostty provides CLI actions via ghostty +<action>. Use ghostty +<action> --help for action-specific help.

Configuration Commands

| Command | Description | |-----------------------------------------|----------------------------------------| | ghostty +show-config | Show current effective configuration | | ghostty +show-config --default | Show default configuration | | ghostty +show-config --default --docs | Show defaults with documentation | | ghostty +validate-config | Validate configuration file for errors | | ghostty +edit-config | Open config file in default editor |

Listing Commands

| Command | Description | |------------------------------------|---------------------------------------| | ghostty +list-fonts | List available fonts (fixed-width) | | ghostty +list-themes | List available colour themes | | ghostty +list-keybinds | Show current keybindings | | ghostty +list-keybinds --default | Show default keybindings | | ghostty +list-colors | List available colour names | | ghostty +list-actions | List all available keybinding actions |

Other Commands

| Command | Description | |-------------------------|------------------------------| | ghostty +version | Show version information | | ghostty +help | Show help | | ghostty +show-face | Show font face information | | ghostty +ssh-cache | Manage SSH terminfo cache | | ghostty +crash-report | Generate crash report | | ghostty +new-window | Open new window (Linux only) | | ghostty +boo | Easter egg |

Launching with Options

Every config key works as a CLI flag:

ghostty --background=282c34 --font-size=14
ghostty -e top                              # Run command in terminal

macOS Note: The ghostty CLI is a helper tool. To launch the terminal use open -na Ghostty.app or open -na Ghostty.app --args --font-size=14.

Keybinding Syntax

Format: keybind = trigger=action

Triggers

Modifiers: shift, ctrl/control, alt/opt/option, super/cmd/command

keybind = ctrl+a=select_all
keybind = ctrl+shift+t=new_tab
keybind = super+backquote=toggle_quick_terminal

Physical keys (W3C codes): KeyA, key_a, Digit1, BracketLeft

Physical keys have higher priority than unicode codepoints
Use for non-US keyboard layouts

Key sequences (leader keys):

keybind = ctrl+a>n=new_window      # Press ctrl+a, release, press n
keybind = ctrl+a>ctrl+n=new_window # Both with ctrl

Sequences wait indefinitely for next key.

Prefixes

| Prefix | Effect | |----------------|---------------------------------------------------------------------------------------| | global: | System-wide (macOS: needs Accessibility permissions; Linux: needs XDG Desktop Portal) | | all: | Apply to all terminal surfaces | | unconsumed: | Don't consume input (passes through) | | performable: | Only consume if action succeeds |

Combine prefixes: global:unconsumed:ctrl+a=reload_config

Note: Sequences cannot be used with global: or all: prefixes.

Special Values

keybind = clear - Remove ALL keybindings
keybind = ctrl+a=unbind - Remove specific binding
keybind = ctrl+a=ignore - Prevent processing by Ghostty and terminal

Shell Integration

Auto-injection for: bash, zsh, fish, elvish

shell-integration = detect    # Default - auto-detect shell
shell-integration = none      # Disable auto-injection
shell-integration = fish      # Force specific shell

Shell Integration Features

shell-integration-features = cursor,sudo,title
shell-integration-features = no-cursor    # Disable specific feature

| Feature | Description | |----------------|-------------------------------| | cursor | Blinking bar at prompt | | sudo | Preserve terminfo with sudo | | title | Set window title from shell | | ssh-env | SSH environment compatibility | | ssh-terminfo | Auto terminfo on remote hosts |

What Shell Integration Enables

Smart close (no confirm when at prompt)
New terminals start in previous terminal's directory
Prompt resizing via redraw
Ctrl/Cmd+triple-click selects command output
jump_to_prompt keybinding works
Alt/Option+click repositions cursor at prompt

Manual Setup (if auto-injection fails)

Bash (add to ~/.bashrc at top):

if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
    builtin source "${GHOSTTY_RESOURCES_DIR}/shell-integration/bash/ghostty.bash"
fi

Zsh:

source ${GHOSTTY_RESOURCES_DIR}/shell-integration/zsh/ghostty-integration

Fish:

source "$GHOSTTY_RESOURCES_DIR"/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish

macOS Note: /bin/bash does NOT support automatic shell integration. Install Bash via Homebrew or manually source the script.

Common Configuration Patterns

Theme with Light/Dark Mode

theme = light:catppuccin-latte,dark:catppuccin-mocha

Quick Terminal (Drop-down)

quick-terminal-position = top
quick-terminal-size = 50%
quick-terminal-autohide = true
keybind = global:super+backquote=toggle_quick_terminal

Custom Colour Palette

palette = 0=#1d2021
palette = 1=#cc241d
# ... (0-255 supported)

Font Configuration

font-family = "JetBrains Mono"
font-family-bold = "JetBrains Mono Bold"
font-size = 14
font-feature = -calt        # Disable ligatures
font-feature = -liga

Background Transparency

background-opacity = 0.9
background-blur = true      # macOS, KDE Plasma only

Platform-Specific Notes

macOS Only:

window-position-x/y, window-save-state, window-step-resize
window-vsync, window-colorspace
macos-titlebar-style, toggle_window_float_on_top
font-thicken, font-thicken-strength
toggle_visibility, undo, redo, check_for_updates
Global keybindings require Accessibility permissions

Linux/GTK Only:

window-title-font-family, window-subtitle
window-titlebar-background/foreground (requires window-theme = ghostty)
window-show-tab-bar, gtk-single-instance
toggle_maximize, toggle_window_decorations
toggle_tab_overview, toggle_command_palette
prompt_surface_title

Linux Wayland Only:

quick-terminal-keyboard-interactivity
gtk-quick-terminal-layer, gtk-quick-terminal-namespace

FreeType (Linux) Only:

freetype-load-flags

Reference Files

For complete option and keybinding references, load:

references/options.md - All config options by category (font, colour, window, etc.)
references/keybindings.md - All keybinding actions with parameters

Load these when you need specific option details, valid values, or keybinding action syntax.