Skip to main content

​
Configuration File

Ghostty uses a simple text-based configuration format. The configuration file is located at:
  • Linux/BSD: $XDG_CONFIG_HOME/ghostty/config or ~/.config/ghostty/config
  • macOS: ~/.config/ghostty/config
The configuration file uses a simple key = value format. Lines starting with # are comments.

​
Basic Configuration Structure

# Basic example
font-family = JetBrains Mono
font-size = 14
theme = rose-pine

# Window settings
window-padding-x = 4
window-padding-y = 4

# Key bindings
keybind = ctrl+shift+c=copy_to_clipboard
keybind = ctrl+shift+v=paste_from_clipboard

​
Loading Configuration

​
Default Configuration Files

By default, Ghostty loads configuration from the XDG config path: 
$XDG_CONFIG_HOME/ghostty/config
You can disable loading default configuration files using --config-default-files=false on the command line.

​
Additional Configuration Files

Use the config-file directive to load additional configuration: 
config-file = ~/.config/ghostty/keybinds.conf
config-file = ~/.config/ghostty/colors.conf
Prepend a ? character to suppress errors:
config-file = ?~/.config/ghostty/optional.conf
Configuration files are loaded after the configuration they’re defined in. Later values override earlier ones.
font-size = 12
config-file = "other.conf"  # If this sets font-size = 14
# Final font-size will be 14

​
Validating Configuration

Validate your configuration without starting Ghostty: 
ghostty +validate-config
This will check for syntax errors and invalid values.

​
Viewing Current Configuration

Show all currently active configuration values: 
ghostty +show-config
This is useful for debugging which values are actually being used, especially when using multiple config files.

​
Reloading Configuration

Ghostty supports runtime configuration reloading for most settings.

​
Via Keybinding

The default keybind is:
cmd+comma or use the reload_config action

​
What Can Be Reloaded?

Most configuration options can be reloaded at runtime. Options that cannot be reloaded are noted in their documentation.
Things that can be reloaded:
  • Colors and themes
  • Font settings (for terminals that haven’t manually adjusted font size)
  • Keybindings
  • Window padding
  • Custom shaders
Things that cannot be reloaded:
  • language (requires full restart)
  • background-opacity on macOS (requires full restart)
  • Window decoration changes (applies to new windows only)

​
CLI Arguments vs Config File

CLI arguments override config file settings: 
# Config file has: font-size = 12
ghostty --font-size=16  # Uses 16, not 12

​
Special CLI Syntax

Some configurations have special CLI shortcuts: 
# Execute a command
ghostty -e nvim file.txt

# This sets initial-command and forces some behaviors:
# - gtk-single-instance=false
# - quit-after-last-window-closed=true
# - shell-integration=detect (if not none)

​
Configuration Commands

Ghostty provides several + commands for working with configuration:
CommandDescription
ghostty +validate-configCheck configuration for errors
ghostty +show-configDisplay all active configuration
ghostty +list-fontsList available fonts
ghostty +list-themesList available themes
ghostty +list-actionsList all keybind actions
ghostty +list-keybindsShow all configured keybinds
ghostty +list-keybinds
This shows all active keybindings, including defaults.

​
Configuration Organization

For complex setups, organize configuration into multiple files: 
# ~/.config/ghostty/config
config-file = ~/.config/ghostty/appearance.conf
config-file = ~/.config/ghostty/fonts.conf
config-file = ~/.config/ghostty/keybinds.conf
config-file = ~/.config/ghostty/shell.conf
Avoid circular dependencies! Configuration files that include each other will cause an error.

​
Platform-Specific Configuration

Some options only apply to specific platforms: 
# macOS only
macos-titlebar-style = transparent
macos-option-as-alt = true

# GTK/Linux only
gtk-toolbar-style = both
gtk-single-instance = true
Platform-specific options are silently ignored on unsupported platforms.

​
Conditional Configuration

While Ghostty doesn’t have built-in conditionals, you can use separate config files per platform: 
# Load platform-specific config
config-file = ~/.config/ghostty/$(uname -s).conf

​
Next Steps

Appearance

Configure colors, themes, and visual styles

Fonts

Set up fonts and typography

Keybindings

Customize keyboard shortcuts

Window Settings

Control window behavior and decorations