Ghostty Cheatsheet

Appearance and Themes

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

Themes

theme = catppuccin-mocha
theme = /Users/me/.config/ghostty/themes/mine
theme = light:rose-pine-dawn,dark:rose-pine

Ghostty ships hundreds of built-in themes, sourced from iterm2-color-schemes and refreshed weekly on main. List them with a live preview:

ghostty +list-themes

Name lookup is case sensitive on case-sensitive filesystems, and a name may not contain a path separator unless it is an absolute path. Two directories are searched, in order:

1. $XDG_CONFIG_HOME/ghostty/themes 2. $prefix/share/ghostty/themes (on macOS, Ghostty.app/Contents/Resources/ghostty/themes)

Light and dark

theme = light:NAME,dark:NAME follows the system appearance automatically. Both halves are required in that form, whitespace is trimmed, and order does not matter.

A theme file is an ordinary config file, so it can set any option, not just colors. It is loaded first, which means anything you set in your own config overrides the theme. That is the opposite of config-file, which loads last and wins.

A theme from an untrusted source can set arbitrary configuration. The built-in themes are audited to only set safe options. Read a downloaded theme before you use it.

theme and config-file are silently ignored inside a theme file.

Colors

Key	Format
`background`	`#RRGGBB`, `RRGGBB`, or an X11 color name
`foreground`	same
`cursor-color`	same
`cursor-text`	same, or `cell-foreground` / `cell-background` since 1.2.0
`selection-foreground` / `selection-background`	same
`palette`	`palette = N=#RRGGBB` for N in 0–255, repeatable
`minimum-contrast`	`1`–`21`, WCAG 2.0 contrast ratio

background = 1e1e2e
foreground = cdd6f4
palette = 0=#45475a
palette = 1=#f38ba8
minimum-contrast = 1.1

minimum-contrast = 1.1 is the practical setting: it only rescues text that would be invisible against its own background. Higher values push text toward pure black or white. It does not apply to emoji or images.

ghostty +list-colors prints the named X11 colors you can use by name.

Transparency and blur

Key	Values
`background-opacity`	`0`–`1`, default `1.0`
`background-opacity-cells`	apply opacity to cell backgrounds too
`background-blur`	`true`, `false`, `macos-glass-regular`, `macos-glass-clear`, or an integer radius

background-opacity = 0.92
background-blur = 20

Padding and window chrome

Key	Default	Notes
`window-padding-x`	`2`	one value, or `left,right`
`window-padding-y`	`2`	one value, or `top,bottom`
`window-padding-balance`	`false`	spread leftover pixels across all four edges
`window-padding-color`	`background`	or `extend`, `extend-always`
`window-decoration`	`auto`	`auto`, `client`, `server`, `none`
`macos-titlebar-style`	`transparent`	`native`, `transparent`, `tabs`, `hidden`
`macos-window-shadow`	`true`
`window-colorspace`	`srgb`
`window-vsync`	`true`	macOS only, `false` cuts latency but can tear

Padding is in points and scales with display DPI. Set it too large and the grid collapses to nothing, with a warning in the logs. window-padding-x and -y changes only apply to newly created terminals.

extend fills the padding with the nearest cell's background color, but it deliberately backs off when the nearest row uses the default background, is a shell prompt, or contains a perfect-fit powerline glyph. extend-always skips those heuristics.

Cursor

Key	Values	Default
`cursor-style`	`block`, `bar`, `underline`, `block_hollow`	`block`
`cursor-style-blink`	blank, `true`, `false`	blank
`cursor-opacity`	`0`–`1`	`1`
`cursor-click-to-move`	`true` / `false`	`false`

cursor-style is only the default. A running program can still request a style with DECSCUSR (CSI q), and shell integration turns the cursor into a bar at the prompt regardless of this setting. Disable that with shell-integration-features = no-cursor.

Leaving cursor-style-blink blank makes Ghostty honor DEC mode 12. Setting it to anything, including true, makes Ghostty ignore DEC mode 12 while still respecting DECSCUSR.