Ghostty User Guide

Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration. It runs on macOS (native AppKit/SwiftUI app) and Linux (native GTK4 + libadwaita app), reads a single plain-text configuration file, and ships with a huge set of built-in themes, full keyboard customization, splits, tabs, a drop-down "quick terminal," a command palette, GPU-rendered custom shaders, and modern terminal protocols (Kitty graphics, Kitty keyboard, OSC 8 hyperlinks, and more).

This guide is for people who use Ghostty: installing it, configuring it, and getting the most out of its features. For architecture, build instructions, packaging, and internals, see the companion Admin Guide.

Note

Ghostty's application identifier is com.mitchellh.ghostty and it advertises itself to programs as TERM=xterm-ghostty. You will see both values referenced throughout this guide.

1. Quick Start

After installing Ghostty, launch it like any other application. Ghostty works out of the box with sensible defaults — no configuration is required.

To start customizing, create a configuration file and reload:

macOS

mkdir -p ~/.config/ghostty
$EDITOR ~/.config/ghostty/config

Linux

mkdir -p ~/.config/ghostty
$EDITOR ~/.config/ghostty/config

Add a few options:

# ~/.config/ghostty/config
theme = catppuccin-mocha
font-family = JetBrains Mono
font-size = 14
background-opacity = 0.95
keybind = ctrl+shift+enter=new_split:right

Reload the configuration without restarting:

• macOS: Cmd+Shift+,
• Linux: Ctrl+Shift+,

Tip

Run ghostty +show-config --default --docs to print every configuration option together with its documentation, or open the config in your editor directly with ghostty +edit-config.

A minimal first-week checklist:

• [ ] Pick a theme: ghostty +list-themes
• [ ] Set your font: ghostty +list-fonts
• [ ] Learn the default split/tab keybinds: ghostty +list-keybinds
• [ ] Bind a quick terminal: keybind = global:cmd+grave_accent=toggle_quick_terminal
• [ ] Confirm shell integration is active (cursor turns to a bar at the prompt)

2. Requirements

Important

Many configuration options are platform-specific. Throughout this guide, options are tagged with macOS only, GTK/Linux only, or Linux Wayland only where relevant. Setting a platform-specific option on the wrong platform is harmless — it is silently ignored.

3. Installation

3.1 macOS

The recommended way to install Ghostty on macOS is to download the official application from ghostty.org or via Homebrew:

Homebrew

brew install --cask ghostty

Manual

1. Download Ghostty.dmg from ghostty.org
2. Open the DMG and drag Ghostty.app into /Applications
3. Launch Ghostty from Spotlight or Finder

Ghostty on macOS includes a built-in auto-updater (powered by Sparkle). See Auto-Update to control its behavior.

3.2 Linux

Ghostty is distributed through Linux package managers and as Flatpak/Snap packages. Use your distribution's package manager where available:

Flatpak

flatpak install flathub com.mitchellh.ghostty

Snap

snap install ghostty --classic

Distro packages

Ghostty is packaged for many distributions (Arch, Fedora, NixOS, and others).
Search your package manager for "ghostty".

Note

Ghostty on Linux is distributed via package managers rather than a built-in auto-updater, so the auto-update options have no effect on Linux.

3.3 Build from source

Ghostty is written in Zig and uses the Zig build system. Building from source is covered in detail in the Admin Guide, but the short version is:

git clone https://github.com/ghostty-org/ghostty
cd ghostty
zig build -Doptimize=ReleaseFast

The resulting binary is placed in zig-out/bin/ghostty along with the
"share" resources directory (themes, terminfo, shell integration).

Warning

Building requires the exact Zig version declared in build.zig.zon (minimum_zig_version). Using a different Zig version will fail the build. See the Admin Guide for the full toolchain and dependency list.

3.4 Verify your installation

ghostty +version

Ghostty 1.x.x
Version: ...
Build Config: ...

4. The ghostty Command Line

Ghostty is both a GUI application and a CLI. When you run ghostty with no arguments it opens a terminal window. It also exposes a set of utility actions, all invoked with a leading +:

ghostty +<action> [options]

You can pass at most one action per invocation. The full reference is in Section 12. The most useful day-to-day actions are:

4.1 Running a command instead of a shell

Use -e to run a specific command instead of your shell:

ghostty -e nvim ~/.config/ghostty/config

Opens a new Ghostty window running the given command directly.

Note

The -e flag automatically forces several behaviors: shell expansion is disabled (the command is assumed to be pre-expanded), gtk-single-instance is disabled so a fresh instance is launched, quit-after-last-window-closed is enabled so Ghostty exits when the command exits, and forced shell-integration injection is disabled.

5. Configuration Basics

5.1 File location

Ghostty reads its configuration from the XDG config directory:

$XDG_CONFIG_HOME/ghostty/config
~/.config/ghostty/config          (if XDG_CONFIG_HOME is unset)

The file config.ghostty is also recognized. The file is plain text and does not exist by default — create it yourself.

5.2 Syntax

The configuration syntax is a simple key = value format, one option per line:

# Comments start with a hash
font-family = JetBrains Mono
font-size = 13
background = 1e1e2e
keybind = ctrl+shift+t=new_tab

Rules of the format:

• One key = value per line. Whitespace around = is ignored.
• Lines beginning with # are comments.
• Repeatable options (like font-family, keybind, palette, link, config-file) may appear multiple times; each line adds an entry rather than overwriting.
• To reset a repeatable list, set it to an empty value (e.g. font-family =) and then add new values.
• Boolean options accept true/false.

Tip

Every configuration key is identical to its command-line flag. Anything you can put in the config file you can also pass as --key=value on the command line, e.g. ghostty --font-size=16 --theme="Rose Pine".

5.3 Including other files

Split your configuration across files with config-file:

config-file = themes-and-colors
config-file = keybinds
config-file = ?optional-machine-local

• Paths are relative to the file that contains the config-file line.
• Prefix a path with ? to silently ignore it if it does not exist.
• Cycles are detected and rejected.

Important

Included files are applied after the configuration that references them. If base contains config-file = override and both set font-size, the value in override wins because it is loaded last.

5.4 Reloading

You can also bind the reload_config action to any key. Note that not all options can be applied at runtime — many only affect newly created terminals, and a few (e.g. language, async-backend, auto-update-channel) require a full restart. Such options are noted in the reference below.

5.5 Inspecting and validating

ghostty +show-config              # effective config (only non-defaults)
ghostty +show-config --default    # include defaults
ghostty +show-config --docs       # include documentation comments
ghostty +validate-config          # validate the default config file
ghostty +validate-config --config-file=path/to/config
ghostty +explain-config font-size # explain one option

6. Fonts

Fonts are one of the most-configured aspects of a terminal. Ghostty has rich font support: fallback chains, per-style families, font features (ligatures), variable fonts, codepoint mapping, and metric adjustments.

6.1 Choosing a font

font-family = JetBrains Mono
font-size = 13

List the fonts Ghostty can find:

ghostty +list-fonts

The font-size is in points and may be fractional (e.g. 13.5). On macOS the default is 13; elsewhere it is 12.

6.2 Fallback fonts and per-style families

font-family is repeatable. Each additional entry is a fallback used when the primary font lacks a glyph (great for mixing a coding font with a CJK or symbol font):

font-family = JetBrains Mono
font-family = Noto Sans CJK SC

You can set distinct families per style:

font-family-bold = JetBrains Mono Bold
font-family-italic = Victor Mono Italic
font-family-bold-italic = Victor Mono Bold Italic

Note

On macOS, emoji default to Apple Color Emoji; on Linux, Noto Emoji. Override by adding a font family that contains emoji glyphs.

6.3 Disabling and synthesizing styles

font-style* options select a named style or disable a style entirely. Set a style to false to disable it (the regular style is used instead):

font-style = Medium
font-style-italic = false   # never use italics

Ghostty can synthesize bold/italic/bold-italic when a font lacks them. Control this with font-synthetic-style:

font-synthetic-style = no-bold-italic   # don't fake bold-italic

Warning

Disabling only bold or italic does not disable bold-italic. To disable faux bold-italic you must list it explicitly.

6.4 Ligatures and font features

Apply OpenType features with font-feature (repeatable or comma-separated):

# Disable programming ligatures
font-feature = -calt
# Disable most ligatures
font-feature = -calt, -liga, -dlig
# Enable a stylistic set
font-feature = ss01

Feature syntax: feat/+feat/feat=1 to enable, -feat/feat=0 to disable, feat=2 to set a value.

Tip

Use fontdrop.info to discover which features your font supports. The default ligature feature in most coding fonts is calt.

You can also control where shaping runs are broken with font-shaping-break. By default Ghostty breaks runs under the cursor (cursor) so editing sees individual characters instead of a ligature.

6.5 Variable fonts

For variable fonts, set axis values with font-variation (and per-style variants):

font-family = Recursive
font-variation = wght=500
font-variation = slnt=-8
font-variation-bold = wght=800

Axis IDs are 4-character tags such as wght, slnt, ital, opsz, wdth.

6.6 Codepoint mapping

Force specific Unicode ranges to a particular font:

font-codepoint-map = U+E0A0-U+E0D4=Symbols Nerd Font
font-codepoint-map = U+4E00-U+9FFF=Noto Sans CJK SC

6.7 Metric adjustments

Fine-tune the cell box and glyph metrics. Values are absolute pixels (1, -2) or percentages (20%, -15%) relative to the original:

adjust-cell-height = 10%
adjust-cursor-thickness = 2

Caution

There is little validation on metric adjustments. Extreme values (e.g. -100%) can make the terminal unusable. Adjust in small steps.

6.8 Other font options

Check which font face renders a specific character:

ghostty +show-face --string="→"

7. Colors and Themes

7.1 Using a built-in theme

Ghostty ships with a large collection of themes (the iTerm2 color schemes collection). Browse them interactively:

ghostty +list-themes

Set one with the theme option:

theme = catppuccin-mocha

The theme value can be a built-in name, a custom theme name, or an absolute path to a theme file. A theme file is simply another Ghostty config file containing color options.

7.2 Light and dark themes

Specify different themes for light and dark mode; Ghostty follows the desktop appearance:

theme = light:rose-pine-dawn,dark:rose-pine

Both light: and dark: must be specified.

Caution

A theme file can set any configuration option, not just colors. Do not use theme files from untrusted sources. The built-in themes are audited to only set safe options. A theme file cannot set theme or config-file.

7.3 Manual colors

Override individual colors. Any of these take precedence over the theme. Colors are hex (#RRGGBB or RRGGBB) or a named X11 color (see ghostty +list-colors).

background = 1e1e2e
foreground = cdd6f4
cursor-color = f5e0dc
cursor-text = 1e1e2e
selection-background = 585b70
selection-foreground = cdd6f4

Tip

cursor-color, cursor-text, and the selection colors accept the special values cell-foreground and cell-background to match the cell under the cursor/selection rather than a fixed color.

7.4 The 256-color palette

palette = 0=#1e1e2e
palette = 1=#f38ba8
# ... indices 0-255, with hex or named colors

Indices may be decimal, or prefixed 0b/0o/0x. If you only set the first 16 colors, enable palette-generate = true to derive the rest (the 6×6×6 cube and grayscale ramp) automatically. palette-harmonious = true reverses the generated ordering for better light/dark behavior.

7.5 Transparency and blur

background-opacity = 0.92
background-blur = true        # or an integer intensity, default 20

• background-opacity — 0 (transparent) to 1 (opaque).
• background-opacity-cells = true — apply opacity even to cells with explicit background colors (useful with Neovim/Tmux).
• background-blur — true, false, or an integer intensity. On macOS 26+ you can use macos-glass-regular or macos-glass-clear for native glass effects.

Note

Background blur is supported on macOS and some Linux desktops (notably KDE Plasma). Under KDE the exact intensity is ignored — KWin has a single global blur setting. On macOS, changing background-opacity requires a full restart.

7.6 Background images

background-image = ~/Pictures/wallpaper.png
background-image-opacity = 0.5
background-image-position = center
background-image-fit = cover     # contain | cover | stretch | none
background-image-repeat = false

PNG and JPEG are supported.

Warning

Background images are currently stored in VRAM per-terminal and repeated across splits. Very large images can significantly increase memory (VRAM) usage.

8. The Cursor

cursor-style = block          # block | bar | underline | block_hollow
cursor-style-blink = true     # blank = follow program, true, false
cursor-color = f5e0dc
cursor-opacity = 1.0
cursor-click-to-move = true

Note

Shell integration sets the cursor to a bar at the prompt regardless of cursor-style. Disable that with shell-integration-features = no-cursor.

9. Mouse and Selection

9.1 Selection behavior

copy-on-select = true                 # true | false | clipboard
selection-clear-on-typing = true
selection-clear-on-copy = false
selection-word-chars = "\t '\"│`|:;,()[]{}<>$"

• copy-on-select — automatically copy selected text. clipboard copies to both the selection and system clipboards. Default true on Linux and macOS.
• selection-word-chars — characters that act as word boundaries for double-click word selection.

9.2 Mouse actions

right-click-action = context-menu     # context-menu | paste | copy | copy-or-paste | ignore
middle-click-action = primary-paste   # primary-paste | ignore
focus-follows-mouse = false
mouse-hide-while-typing = false
click-repeat-interval = 0             # ms; 0 = platform default

9.3 Scrolling and mouse reporting

mouse-scroll-multiplier = 3                   # or precision:0.1,discrete:3
scroll-to-bottom = keystroke,no-output
mouse-reporting = true
mouse-shift-capture = false                   # false | true | always | never

• mouse-reporting — when false, mouse events are never sent to programs, so you can always select with the mouse. Toggle at runtime with the toggle_mouse_reporting action.
• mouse-shift-capture — whether holding Shift while clicking sends the mouse event to the program or extends the selection.

10. Windows, Tabs, and Splits

Ghostty organizes terminals into surfaces arranged as splits within tabs within windows.

10.1 Splits

Splits divide a tab into multiple terminals. The default binds vary by platform; see ghostty +list-keybinds. Common actions to bind:

keybind = ctrl+shift+right=new_split:right
keybind = ctrl+shift+down=new_split:down
keybind = ctrl+shift+l=goto_split:right
keybind = ctrl+shift+z=toggle_split_zoom
keybind = ctrl+shift+e=equalize_splits

Appearance and behavior:

unfocused-split-opacity = 0.7
split-divider-color = 585b70
split-preserve-zoom = navigation
split-inherit-working-directory = true

10.2 Tabs

keybind = ctrl+shift+t=new_tab
keybind = ctrl+shift+page_up=previous_tab
keybind = ctrl+shift+page_down=next_tab
window-new-tab-position = current      # current | end
window-show-tab-bar = auto             # always | auto | never (GTK)
gtk-tabs-location = top                # top | bottom | hidden (GTK)
gtk-wide-tabs = true                   # GTK

10.3 Windows

keybind = ctrl+shift+n=new_window
window-height = 40        # initial size, in grid cells
window-width = 120
window-padding-x = 4
window-padding-y = 4
window-padding-balance = true
maximize = false
fullscreen = false        # false | true | non-native (macOS) | ...
window-save-state = default   # macOS: default | never | always
window-inherit-working-directory = true
window-inherit-font-size = true

Note

On macOS, native tabs and native fullscreen require the titlebar. Tabs do not work with non-native fullscreen modes. If you use tabs, use native fullscreen (fullscreen = true).

11. Configuration Reference

This section is the exhaustive option reference, grouped by area. Defaults shown are the cross-platform defaults unless noted. Platform tags: [mac] macOS only, [gtk] GTK/Linux only, [wl] Linux Wayland only.

11.1 Fonts

11.2 Colors and appearance

11.3 Cursor and mouse

11.4 Window and layout

11.5 Scrollback and scrollbar

11.6 Clipboard and selection safety

11.7 Command and process

11.8 Shell integration

See Section 14 for details.

11.9 Keyboard

11.10 Quick terminal

11.11 Bell and notifications

11.12 Window decoration and titlebar (macOS)

11.13 GTK / Linux

11.14 macOS-specific behavior

11.15 Auto-update (macOS)

11.16 Advanced

12. Command-Line Actions Reference

All actions are invoked as ghostty +<action>.

# Examples
ghostty +list-themes
ghostty +show-config --default --docs | less
ghostty +validate-config --config-file=~/.config/ghostty/config
ghostty +explain-config background-opacity

Tip

+new-window and +toggle-quick-terminal use inter-process communication to control an already-running Ghostty instance — useful for binding to global system shortcuts or scripts.

13. Keybindings

13.1 Syntax

keybind = <trigger>=<action>

A trigger is a +-separated list of modifiers and one key:

keybind = ctrl+shift+t=new_tab
keybind = cmd+c=copy_to_clipboard
keybind = up=scroll_page_up

• Modifiers: shift, ctrl (alias control), alt (aliases opt, option), super (aliases cmd, command).
• Keys: a Unicode character (a, layout-dependent), a physical key code (KeyA/key_a, layout-independent), or a named key (up, f5, enter, insert). Physical keys win over Unicode keys when both are bound.
• catch_all matches any otherwise-unbound key.

13.2 Key sequences (leader keys)

Chain triggers with > to require a sequence:

keybind = ctrl+a>n=new_window
keybind = ctrl+a>t=new_tab

Ghostty waits indefinitely for the next key in a sequence (no timeout). Quote sequences on the command line because > is a shell metacharacter: ghostty --keybind='ctrl+a>n=new_window'.

13.3 Trigger prefixes

Prefix a trigger to change behavior:

keybind = global:cmd+grave_accent=toggle_quick_terminal
keybind = performable:cmd+c=copy_to_clipboard
keybind = unconsumed:ctrl+a=reload_config

Important

global: is only supported on macOS and certain Linux desktops. On macOS it requires Accessibility permission. On Linux it requires a compositor that implements the XDG GlobalShortcuts portal (KDE Plasma 5.27+, GNOME 48+, Hyprland with setup; not wlroots/Sway).

13.4 Chained actions and key tables

Run several actions from one keybind with chain (Ghostty 1.3+):

keybind = ctrl+a=new_window
keybind = chain=goto_split:left
keybind = chain=toggle_fullscreen

Define modal key tables (e.g. a "copy mode") with table/binding syntax and activate them with activate_key_table (Ghostty 1.3+):

keybind = ctrl+a=activate_key_table:nav
keybind = nav/h=goto_split:left
keybind = nav/l=goto_split:right
keybind = nav/escape=deactivate_key_table

13.5 Special keybind values

keybind = clear                 # remove ALL keybinds (including defaults)
keybind = ctrl+x=unbind         # remove a single binding
keybind = ctrl+g=ignore         # black-hole a key
keybind = f1=csi:0m             # send a CSI sequence
keybind = f2=esc:d              # send an ESC sequence
keybind = f3=text:\x15          # send literal text (Zig string literal syntax)

13.6 Modifier remapping

key-remap = ctrl=super
key-remap = left_control=right_alt

Remaps are one-way and not transitive. Use sided names (left_ctrl) to remap a single physical key.

13.7 Action reference

The full, build-accurate list is available via ghostty +list-actions. The following actions can be bound to triggers (and used in command-palette-entry):

Input / text

Clipboard

Font size

Search

Scrolling

Selection

Dump screen to file

Tabs

new_tab, previous_tab, next_tab, last_tab, goto_tab:<n>, move_tab:<n>, toggle_tab_overview, prompt_tab_title, set_tab_title:<s>.

Splits

new_split:<dir>, goto_split:<dir>, toggle_split_zoom, resize_split:<dir>,<n>, equalize_splits, toggle_readonly.

Windows

new_window, close_surface, close_tab:this|other|right, close_window, toggle_maximize, toggle_fullscreen, toggle_window_decorations (Linux), toggle_window_float_on_top (macOS), reset_window_size (macOS), goto_window:previous|next, prompt_surface_title, set_surface_title:<s>.

Application & UI

Key tables

activate_key_table:<name>, activate_key_table_once:<name>, deactivate_key_table, deactivate_all_key_tables, end_key_sequence.

Note

Many actions are platform-specific and report as "not performable" where unsupported. Use performable: triggers to let unsupported keys fall through to the program.

14. Shell Integration

Shell integration unlocks several quality-of-life features:

• New tabs/splits inherit the working directory of the previous terminal.
• Prompt marking (OSC 133) enables jump_to_prompt and click-to-move.
• Closing a terminal sitting at a prompt skips the confirmation dialog.
• Better repainting when resizing with complex prompts.

14.1 Enabling

Automatic injection is on by default:

shell-integration = detect       # none | detect | bash | elvish | fish | nushell | zsh

detect chooses the integration based on your shell binary name. Set a specific shell to force it, or none to disable auto-injection (you can still source the scripts manually).

14.2 Features

Toggle individual features:

shell-integration-features = cursor,no-sudo,title,ssh-env,ssh-terminfo

Tip

For the smoothest SSH experience, enable both ssh-env and ssh-terminfo. Ghostty installs its terminfo remotely and uses xterm-ghostty, falling back to xterm-256color if installation fails. Manage the install cache with ghostty +ssh-cache.

14.3 Remote hosts and terminfo

If a remote host doesn't recognize xterm-ghostty, programs may misbehave. The options above handle this automatically; alternatively, install the terminfo manually or set term = xterm-256color.

15. Notable Features

15.1 The quick terminal

A drop-down ("Quake-style") terminal that slides in from a screen edge on demand. There is no default keybind — bind one (ideally global):

keybind = global:cmd+grave_accent=toggle_quick_terminal
quick-terminal-position = top
quick-terminal-size = 40%
quick-terminal-autohide = true

Limitations: only one instance exists at a time; it is not restored on restart; on Linux it requires Wayland with wlr-layer-shell-v1 (so not GNOME), and slide-in animation requires KDE's "Sliding Popups" KWin plugin. Quick-terminal tabs are Linux-only.

15.2 The command palette

A searchable popup listing actions and their shortcuts:

keybind = cmd+shift+p=toggle_command_palette

Add custom entries:

command-palette-entry = title:Reset Font Style, action:csi:0m
command-palette-entry = title:Focus Right Split, action:goto_split:right

On Linux this requires libadwaita 1.5+.

15.3 Search

keybind = cmd+f=start_search
keybind = cmd+g=navigate_search:next
keybind = cmd+shift+g=navigate_search:previous

Search match colors are configurable (search-foreground, search-background, search-selected-foreground, search-selected-background).

15.4 Clickable links

URLs are matched on hover with Ctrl (Linux) or Cmd (macOS) and open in your default application. OSC 8 hyperlinks are supported. Configure link previews with link-previews (true/false/osc8). Disable automatic URL matching with link-url = false.

15.5 Custom shaders

Apply GPU post-processing shaders (Shadertoy-compatible GLSL):

custom-shader = ~/.config/ghostty/shaders/crt.glsl
custom-shader-animation = true

Shaders receive uniforms like iResolution, iTime, iChannel0 (the terminal screen), plus Ghostty extensions (iCurrentCursor, iPalette, iBackgroundColor, etc.).

Caution

An invalid or aggressive shader can render the window completely black. If that happens, remove the custom-shader line and reload. Shader compile errors only appear in the logs, not as config errors.

15.6 Kitty graphics and images

Ghostty implements the Kitty graphics protocol for inline images. Memory is capped per screen by image-storage-limit (default 320 MB; set to 0 to disable all image protocols).

15.7 The terminal inspector

A built-in debugging overlay showing keyboard events, terminal modes, screen contents, and more:

keybind = cmd+alt+i=inspector:toggle

16. Troubleshooting

Error: programs look broken / wrong colors over SSH

Cause: the remote host doesn't have the xterm-ghostty terminfo entry. Solution: enable shell-integration-features = ssh-terminfo (and ssh-env), or set term = xterm-256color, or install the terminfo on the remote host. Prevention: keep ssh-env/ssh-terminfo enabled.

Error: the window is completely black after adding a shader

Cause: an invalid custom-shader. Solution: remove the custom-shader line and reload (Cmd/Ctrl+Shift+,). Check logs for the compile error. Prevention: develop shaders on shadertoy.com first.

Error: global: keybind does nothing

Cause: missing permission/portal support. Solution (macOS): grant Accessibility permission in System Settings → Privacy & Security → Accessibility. Solution (Linux): use a compositor with the GlobalShortcuts portal (KDE 5.27+, GNOME 48+); wlroots/Sway is unsupported.

Error: Option key types special characters instead of acting as Alt (macOS)

Cause: macOS Option produces Unicode by default. Solution: set macos-option-as-alt = true (or left/right). Prevention: keep this set if you rely on Alt-based shortcuts in shells/editors.

Error: tabs disappear in fullscreen (macOS)

Cause: non-native fullscreen removes the titlebar that native tabs require. Solution: use native fullscreen (fullscreen = true, macos-non-native-fullscreen = false).

Error: ligatures appear where I don't want them

Cause: the font's calt feature. Solution: font-feature = -calt (and -liga, -dlig for more). Ghostty also breaks shaping under the cursor by default.

Error: background blur / transparency not working on Linux

Cause: limited compositor support. Solution: blur is only supported on some desktops (notably KDE Plasma, where it uses KWin's global blur). Enable the KWin "Blur" desktop effect. Prevention: verify your desktop supports it.

Error: terminal uses too much memory

Cause: large scrollback-limit, large background images, or many images. Solution: lower scrollback-limit, reduce image-storage-limit, avoid huge background images (they live in VRAM per terminal).

Error: config change didn't take effect

Cause: many options only apply to new terminals, and a few require a full restart. Solution: open a new window/tab, or fully restart Ghostty. Check the option's notes in Section 11.

Error: +validate-config reports errors

Cause: a malformed option or value. Solution: run ghostty +validate-config to see the exact line and message; use ghostty +explain-config <key> to confirm valid values.

Error: closing a window unexpectedly prompts for confirmation

Cause: confirm-close-surface and an active process. Solution: set confirm-close-surface = false, or enable shell integration so Ghostty knows you're at a prompt.

Error: Ghostty quits when I close the last window (or doesn't)

Cause: quit-after-last-window-closed differs by platform (default true on Linux, false on macOS). Solution: set it explicitly to the behavior you want; on Linux you can add quit-after-last-window-closed-delay.

Error: unsafe-paste confirmation keeps appearing

Cause: clipboard-paste-protection flags multiline/control-char pastes. Solution: keep it on for safety; it normally only triggers for risky content. You can disable with clipboard-paste-protection = false (not recommended).

Error: app icon won't change (macOS Finder)

Cause: the Finder icon is baked into the signed app bundle. Solution: macos-icon only affects the dock/switcher icon, not Finder.

Error: tab overview / command palette missing (Linux)

Cause: libadwaita too old. Solution: tab overview needs libadwaita 1.4+, command palette needs 1.5+. Check with ghostty +version.

17. FAQ

Q: Where is my configuration file? ~/.config/ghostty/config (or $XDG_CONFIG_HOME/ghostty/config). It does not exist by default — create it. ghostty +edit-config opens it.

Q: How do I see every available option? ghostty +show-config --default --docs. For one option, ghostty +explain-config <key>.

Q: How do I list/preview themes? ghostty +list-themes. Set with theme = <name>.

Q: How do I disable ligatures? font-feature = -calt (add -liga, -dlig to remove more).

Q: How do I make the background transparent? background-opacity = 0.9 (and optionally background-blur = true).

Q: Can I have different light/dark themes? Yes: theme = light:rose-pine-dawn,dark:rose-pine.

Q: How do I add a drop-down (Quake) terminal? Bind toggle_quick_terminal, ideally globally: keybind = global:cmd+grave_accent=toggle_quick_terminal.

Q: What is TERM set to, and why does it matter? xterm-ghostty. Remote hosts may not have this terminfo; use the SSH shell integration features or fall back to xterm-256color.

Q: Why does Option+letter type symbols on macOS instead of acting as Alt? That's macOS default behavior. Set macos-option-as-alt = true.

Q: How do I run a single command instead of my shell? ghostty -e <command>.

Q: How do I split the window? Bind new_split:right/down (and navigate with goto_split:...). Defaults vary; see ghostty +list-keybinds.

Q: Why aren't my keybinds working / how do I see the defaults? ghostty +list-keybinds shows all active bindings. Remember keybind = clear removes defaults too.

Q: Does Ghostty support inline images? Yes, via the Kitty graphics protocol (capped by image-storage-limit).

Q: How do I update Ghostty? macOS has a built-in updater (auto-update, check_for_updates). Linux updates through your package manager / Flatpak / Snap.

Q: How do I reset a repeatable option like font-family? Set it to an empty value first (font-family =) then add new entries.

Q: Can a theme change non-color settings? Yes — a theme file can set almost any option (but not theme/config-file). Only use themes you trust.

Q: How do I make a keybind work even when Ghostty isn't focused? Prefix it with global: (macOS Accessibility permission / Linux GlobalShortcuts portal required).

Q: How do I rename a tab or window? Bind prompt_tab_title / prompt_surface_title, or use set_tab_title:<text>.

Q: How do I customize the dock icon on macOS? Use macos-icon (official variants), or macos-icon = custom with macos-custom-icon = /path/to/icon.

18. Quick Reference

Config file: ~/.config/ghostty/config

Reload: Cmd+Shift+, (macOS) / Ctrl+Shift+, (Linux)

Essential CLI:

ghostty +list-themes        # themes
ghostty +list-fonts         # fonts
ghostty +list-keybinds      # keybinds
ghostty +list-actions       # bindable actions
ghostty +show-config --default --docs   # all options + docs
ghostty +edit-config        # open config
ghostty +validate-config    # validate
ghostty -e <command>        # run a command

Starter config:

theme = light:rose-pine-dawn,dark:rose-pine
font-family = JetBrains Mono
font-size = 13
background-opacity = 0.95
cursor-style = bar
copy-on-select = clipboard
keybind = ctrl+shift+enter=new_split:right
keybind = ctrl+shift+t=new_tab
keybind = global:cmd+grave_accent=toggle_quick_terminal
shell-integration-features = cursor,title,ssh-env,ssh-terminfo