Ghostty Cheatsheet

Configuration File

Use this Ghostty reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

Syntax

One key = value per line. Whitespace around = is ignored, comments are # on their own line, and blank lines are ignored.

# Comments must be on their own line, not trailing.
background = 282c34
foreground = ffffff
font-family = "JetBrains Mono"

# An empty value resets the key to its default.
font-family =

- Keys are case sensitive and always lowercase. Background is not background. - Quotes are optional. font-family = "JetBrains Mono" equals font-family = JetBrains Mono. - Repeatable keys (font-family, font-feature, keybind, config-file, env) append. To replace instead of append, set key = "" first, then set the value. - Every key is also a CLI flag: ghostty --background=282c34. - Values set on the CLI automatically clear values from config files for repeatable keys, so you do not need --font-family="" first.

File locations and load order

$XDG_CONFIG_HOME/ghostty/config.ghostty
$XDG_CONFIG_HOME/ghostty/config
~/Library/Application Support/com.mitchellh.ghostty/config.ghostty   (macOS)
~/Library/Application Support/com.mitchellh.ghostty/config           (macOS)

All existing files load in that order and later values win. config.ghostty is the name since 1.2.3, config is the older name and still works.

Splitting across files

config-file pulls in another file. Paths are relative to the file that contains the directive, or to the current directory for a CLI flag. A ? prefix makes the file optional.

config-file = colors.ghostty
config-file = ?local.ghostty          # ignored if missing
config-file = "?literal-question.conf" # quote to keep a literal ?

config-file entries are processed at the end of the current file, so keys in the included file override keys set before it. This is the opposite of how theme files work, which load first and lose to your own settings.

Cycles are detected and produce a warning. config-default-files = false is a CLI-only flag that skips the default paths entirely.

Options people actually set

Key	Default	Notes
`font-family`	embedded JetBrains Mono	repeatable, later entries are fallbacks
`font-size`	platform default	points, non-integer allowed
`font-feature`	—	`-calt` disables programming ligatures
`theme`	none	built-in name, custom name, or absolute path
`background`	`282c34`	`#RRGGBB`, `RRGGBB`, or an X11 color name
`foreground`	`ffffff`	same formats
`background-opacity`	`1.0`	`0`–`1`
`background-blur`	`false`	`true`, `false`, `macos-glass-regular`, `macos-glass-clear`, or a radius
`window-padding-x`	`2`	one value, or `left,right`
`window-padding-y`	`2`	one value, or `top,bottom`
`cursor-style`	`block`	`block`, `bar`, `underline`, `block_hollow`
`cursor-style-blink`	unset	unset respects DEC mode 12
`scrollback-limit`	`10000000`	bytes, so 10MB, not lines
`scrollbar`	`system`	or `never`
`mouse-hide-while-typing`	`false`
`copy-on-select`	`true`	or `false`, or `clipboard`
`confirm-close-surface`	`true`	or `false`, or `always`
`shell-integration`	`detect`	`none`, `detect`, `bash`, `elvish`, `fish`, `nushell`, `zsh`
`macos-option-as-alt`	unset	`true`, `false`, `left`, `right`
`macos-titlebar-style`	`transparent`	`native`, `transparent`, `tabs`, `hidden`
`window-decoration`	`auto`	`auto`, `client`, `server`, `none`
`unfocused-split-opacity`	`0.7`	`1` disables the dimming
`link-url`	`true`	cmd or ctrl hover to open URLs
`clipboard-paste-protection`	`true`	warns on unsafe pastes

Reload and inspect

# Reload at runtime: cmd+shift+, on macOS, ctrl+shift+, on Linux
# or bind it yourself:
#   keybind = ctrl+alt+r=reload_config

ghostty +show-config                  # your resolved config, changes only
ghostty +show-config --default --docs # every option with its doc comment
ghostty +validate-config              # parse errors and diagnostics
ghostty +edit-config                  # open in the configured editor

+show-config defaults to --changes-only=true. Blank entries such as font-family = in its output mean the key is defaulting, which is valid syntax and exists so a doc comment has something to attach to.

Offline reference

The full option reference ships with every install, generated from the same source as the website.

Where	Path
Markdown and HTML	`$prefix/share/ghostty/docs`
Man pages	`$prefix/share/man`
CLI	`ghostty +show-config --default --docs`
Source	`src/config/Config.zig` in the repo

On macOS $prefix is Ghostty.app/Contents/Resources. Built from source it is zig-out, or whatever you passed to --prefix.