--- type: reference title: Ghostty Configuration Options — Complete Reference description: Every configuration option for Ghostty, organized by category with types, defaults, and usage examples. tags: - terminal - ghostty - configuration - reference verified: 2026-08-28 --- # Ghostty Configuration Reference Complete option catalog for [Ghostty](https://ghostty.org). See [Overview](index.md) for setup and quick-start. --- ## Font Configuration ### `font-family` **Type**: String (repeatable) Primary font family with fallback support. ```ini font-family = "JetBrains Mono" font-family = "Noto Sans Mono" # fallback ``` Styles (bold, italic, bold-italic) are automatically found. Use `ghostty +list-fonts` to see available fonts. ### `font-style`, `font-style-bold`, `font-style-italic`, `font-style-bold-italic` **Type**: String or `false` A named font style from the font's own style string, for example "Heavy" or "Semibold". Set to `false` to completely disable a style. ### `font-synthetic-style` **Type**: String (comma-separated) Control whether Ghostty synthesizes missing styles. Values: `true`, `false`, `bold,italic,bold-italic`, `no-bold,no-italic`. ### `font-feature` **Type**: String (repeatable, comma-separated) OpenType font features. Enable: `feat`, `+feat`, `feat on`, `feat=1`. Disable: `-feat`, `feat off`, `feat=0`. ```ini font-feature = -calt # disable programming ligatures font-feature = -liga # disable standard ligatures ``` ### `font-size` **Type**: Number (can be non-integer, in points) ```ini font-size = 12 font-size = 13.5 # 27px on a 2x DPI display ``` ### `font-variation` **Type**: String in `id=value` format (repeatable) Variable font axis values (4-character IDs). ```ini font-variation = wght=700 font-variation = wdth=100 ``` ### `font-codepoint-map` **Type**: String (repeatable) Force Unicode codepoints to map to a specific font. ```ini font-codepoint-map = U+2500-U+257F=JetBrains Mono ``` ### `clipboard-codepoint-map` **Type**: String (repeatable) Map codepoints to replacement values when copying to clipboard. ```ini clipboard-codepoint-map = U+2500=U+002D # box drawing → hyphen clipboard-codepoint-map = U+03A3=SUM # Greek sigma → "SUM" ``` ### `grapheme-width-method` **Type**: String Width calculation method: `unicode` (default, correct but can cause cursor-desync) or `legacy` (wcswidth, maximizes compatibility). --- ## Alpha Blending & Rendering ### `alpha-blending` **Type**: String Color space for alpha blending (available since 1.1.0): `native` (OS-native, macOS default), `linear` (eliminates darkening artifacts), `linear-corrected` (Linux default). --- ## Cell Adjustments All `adjust-*` options accept integers (1, -1) or percentages (20%, -15%). | Option | Description | |--------|-------------| | `adjust-cell-width` | Cell width adjustment | | `adjust-cell-height` | Cell height (also centers font vertically, adjusts Powerline glyphs) | | `adjust-font-baseline` | Baseline position | | `adjust-underline-position` | Underline position | | `adjust-underline-thickness` | Underline thickness | | `adjust-strikethrough-position` | Strikethrough position | | `adjust-strikethrough-thickness` | Strikethrough thickness | | `adjust-overline-position` | Overline position | | `adjust-overline-thickness` | Overline thickness | | `adjust-cursor-thickness` | Bar/rect cursor thickness | | `adjust-cursor-height` | Cursor height | | `adjust-box-thickness` | Box drawing character thickness | | `adjust-icon-height` | Nerd font icon height (available since 1.2.0) | **Warning**: Invalid values, for example -100%, can make the terminal unusable. --- ## Theme & Colors ### `theme` **Type**: String Theme name, absolute path, or light/dark pair: `light:Rose Pine Dawn,dark:Rose Pine`. ### `background` / `foreground` **Type**: Color (`#RRGGBB`, `RRGGBB`, or named X11 color) ### `palette` **Type**: `N=COLOR` (repeatable, N = 0–255) ```ini palette = 0=#1d1f21 palette = 0x00=#1d1f21 palette-generate = true ``` Only set 0-15 for most themes; 16-255 auto-generated if `palette-generate` is enabled. ### `bold-color` **Type**: Color or `bright` (available since 1.2.0) Replaces deprecated `bold-is-bright`. ### `minimum-contrast` **Type**: Number (1-21) Minimum contrast ratio (WCAG 2.0). Value of 3+ = avoid hard-to-read text. --- ## Appearance ### `background-image` **Type**: Path (PNG or JPEG, available since 1.2.0) Per-terminal background image. **Warning**: Currently duplicated in VRAM per-terminal. ### `background-opacity` **Type**: Number (0-1) Window transparency. On macOS, disabled in native fullscreen. ### `background-blur` **Type**: Number, `true`, `false`, or macOS special values Blur background when opacity < 1. macOS special: `macos-glass-regular`, `macos-glass-clear` (macOS 26.0+). --- ## Selection ### `copy-on-select` **Type**: Boolean or `clipboard` Automatically copy selected text. `clipboard` copies to both selection and system clipboard. ### `selection-clear-on-typing` **Type**: Boolean (available since 1.2.0) Clear selection when typing. Default: `true`. --- ## Cursor ### `cursor-style` **Type**: String `block`, `bar`, `underline`, `block_hollow`. Programs can override via DECSCUSR. ### `cursor-click-to-move` **Type**: Boolean Click to move cursor at prompts (requires shell integration). Default: `true`. --- ## Mouse ### `mouse-hide-while-typing` **Type**: Boolean Hide mouse when typing. ### `mouse-reporting` **Type**: Boolean Allow terminal applications to receive mouse events. Default: `true`. Toggle with `toggle_mouse_reporting` keybind. --- ## Scrolling ### `scroll-to-bottom` **Type**: String (comma-separated) When to auto-scroll: `keystroke` (default), `output`. ### `scrollback-limit` **Type**: Integer (bytes) Scrollback buffer size. Default: `10000000` (10 MB). --- ## Split Panes ### `unfocused-split-opacity` **Type**: Number (0.15-1) Opacity of unfocused split. Default: `0.7`. Minimum: `0.15`. ### `split-divider-color` **Type**: Color (available since 1.1.0) Color of split dividers. --- ## Shell Integration ### `shell-integration` **Type**: String `none`, `detect` (default), `bash`, `elvish`, `fish`, `nushell`, `zsh`. `detect` auto-detects by filename. ### `shell-integration-features` **Type**: String (comma-separated) Features: `cursor`, `sudo`, `title`, `ssh-env`, `ssh-terminfo`, `path`. Negate with `no-`. --- ## Environment & Command ### `command` **Type**: String Shell/command to run. Uses `/bin/sh -c` for argument expansion unless prefixed with `direct:` or `shell:`. ### `env` **Type**: `KEY=VALUE` (repeatable, available since 1.2.0) Extra environment variables. Set `env =` to reset all. --- ## Window Settings ### `maximize` **Type**: Boolean (available since 1.1.0) Start maximized. Default: `false`. ### `fullscreen` **Type**: String `false`, `true` (native), `non-native`, `non-native-visible-menu`, `non-native-padded-notch` (macOS only). ### `window-decoration` **Type**: String or Boolean (available since 1.1.0) `none`, `auto` (default), `client`, `server`. Booleans: `true` = `auto`, `false` = `none`. ### `window-padding-x` / `window-padding-y` **Type**: Number or `X,Y` Padding in points. Default: `2`. --- ## Clipboard ### `clipboard-read` / `clipboard-write` **Type**: String `ask`, `allow`, `deny`. Defaults: `ask` / `allow`. ### `clipboard-paste-protection` **Type**: Boolean Require confirmation before pasting potentially unsafe text. Default: `true`. --- ## Notifications & Bell ### `bell-features` **Type**: String (comma-separated, available since 1.2.0) Features: `system`, `audio`, `attention` (default), `title` (default), `border`. Negate with `no-`. ### `desktop-notifications` **Type**: Boolean Allow apps to show desktop notifications via escape sequences. Default: `true`. --- ## Custom Shaders ### `custom-shader` **Type**: Path (repeatable) GLSL shader file path. Compatible with Shadertoy. Receives uniforms: `iChannel0` (screen texture), `iResolution`, `iTime`, `iCursorColor`, `iPalette[256]`, and more. ### `custom-shader-animation` **Type**: Boolean or `always` Run animation loop even when unfocused: `always`. --- ## Keybindings ### Format ```ini keybind = trigger=action keybind = chain=action # chain with previous keybind ``` **Modifiers**: `shift`, `ctrl`/`control`, `alt`/`opt`/`option`, `super`/`cmd`/`command` **Prefixes**: `all:`, `global:`, `unconsumed:`, `performable:`, `physical:` ### Key Tables (available since 1.3.0) ```ini keybind = foo/ctrl+a=new_window keybind = foo/ # define and clear table ``` ### Key Remap ```ini key-remap = ctrl=super key-remap = left_control=right_alt ``` --- ## VT/Compatibility ### `term` **Type**: String TERM environment variable. Default: `xterm-ghostty`. ### `async-backend` **Type**: String (available since 1.2.0, Linux only) `auto` (default), `epoll`, `io_uring`. macOS always uses `kqueue`. --- ## Miscellaneous ### `confirm-close-surface` **Type**: Boolean or `always` Confirm before closing surface. Default: `true`. ### `focus-follows-mouse` **Type**: Boolean Auto-focus split under mouse. Default: `false`. ### `right-click-action` **Type**: String `context-menu` (default), `paste`, `copy`, `copy-or-paste`, `ignore`. --- ## Appendix: Default Keybindings | Keybind | Action | |---------|--------| | `ctrl+shift+,` | `reload_config` | | `ctrl+,` | `open_config` | | `copy` | `copy_to_clipboard:mixed` | | `paste` | `paste_from_clipboard` | | `ctrl+shift+c` | `copy_to_clipboard:mixed` | | `ctrl+shift+v` | `paste_from_clipboard` | | `ctrl+=` / `ctrl++` | `increase_font_size:1` | | `ctrl+-` | `decrease_font_size:1` | | `ctrl+0` | `reset_font_size` | | `shift+PageUp` | `scroll_page_up` | | `shift+PageDown` | `scroll_page_down` | | `shift+Home` | `scroll_to_top` | | `shift+End` | `scroll_to_bottom` | | `ctrl+shift+Tab` | `previous_tab` | | `ctrl+Tab` | `next_tab` | | `ctrl+shift+n` | `new_window` | | `ctrl+shift+w` | `close_tab:this` | | `ctrl+shift+q` | `quit` | | `ctrl+shift+t` | `new_tab` | | `ctrl+shift+o` | `new_split:right` | | `ctrl+shift+e` | `new_split:down` | | `ctrl+shift+f` | `start_search` | | `Escape` | `end_search` | | `ctrl+shift+a` | `select_all` | | `alt+1`-`alt+9` | `goto_tab:1`-`goto_tab:9` | | `ctrl+Enter` | `toggle_fullscreen` | | `ctrl+shift+P` | `toggle_command_palette` | --- ## Cross-References - See [Overview](index.md) for CLI actions and quick-start. - The [AGENTS.md Format](/core/agents-md-format.md) governs how agent behavior contracts reference this configuration.