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.