sammcj/ghostty-config

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

Since Ghostty 1.2.3 the config file is named config.ghostty (the .ghostty extension lets editors apply syntax highlighting). The extensionless config name is still loaded for backwards compatibility.

XDG Path (All Platforms):

• $XDG_CONFIG_HOME/ghostty/config.ghostty
• $XDG_CONFIG_HOME/ghostty/config
• XDG_CONFIG_HOME defaults to ~/.config if undefined

macOS Additional Path:

• ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty
• ~/Library/Application Support/com.mitchellh.ghostty/config

Loading order: all matching files are loaded, later files overriding earlier ones. Within a location config.ghostty loads before config. On macOS all macOS-path files load after all XDG-path files, so the macOS path wins on conflicts. Config is optional; with no file Ghostty uses its defaults.

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.

Named key tables (Ghostty 1.3+): Switch into a modal set of bindings with activate_key_table:name / activate_key_table_once:name, leave with deactivate_key_table. Use end_key_sequence to flush a partial sequence to the terminal. In-terminal search (search, start_search, navigate_search, end_search) is also available. See references/keybindings.md.

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

1. Smart close (no confirm when at prompt)
2. New terminals start in previous terminal's directory
3. Prompt resizing via redraw
4. Ctrl/Cmd+triple-click selects command output
5. jump_to_prompt keybinding works
6. 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
• toggle_secure_input, toggle_background_opacity, reset_window_size
• 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, show_gtk_inspector, show_on_screen_keyboard

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.