Troubleshooting

The TERM problem

Ghostty sets TERM=xterm-ghostty because it is not xterm and claiming to be one causes subtler bugs than an unknown terminal does. The terminfo entry ships with Ghostty, so local programs work, but a remote host that has never seen Ghostty has no entry for it.

Symptoms on ssh: Error opening terminal: xterm-ghostty, a shell that starts then immediately errors, or a broken-looking less and vim.

# Check whether a host knows the entry
infocmp -x xterm-ghostty > /dev/null && echo ok

Never "fix" it by hardcoding term = xterm-256color in your config. That disables Ghostty features that depend on its own capabilities. Fix the remote host instead, or override TERM for that one host.

Installing terminfo on a remote host

The one-liner: pipe the local entry into tic on the remote.

infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x -

Expect a tic warning about an unknown capability like Smulx or Sync. That is harmless. On macOS before Sonoma the system infocmp is too old for -x, so install a current one:

brew install ncurses
/opt/homebrew/opt/ncurses/bin/infocmp -x xterm-ghostty \
  | ssh YOUR-SERVER -- tic -x -

Alternatives when you cannot write terminfo on the remote:

# ~/.ssh/config, needs OpenSSH 8.7+
Host legacy-box
  SetEnv TERM=xterm-256color

# One-off, without touching config
TERM=xterm-256color ssh YOUR-SERVER

Ghostty's ssh-terminfo shell integration feature automates the tic step and caches which hosts are done. Inspect that cache with ghostty +ssh-cache.

Environment variables not arriving

Ghostty sets COLORTERM=truecolor, TERM_PROGRAM=ghostty, and TERM_PROGRAM_VERSION. sshd only forwards variables it is told to accept, so add this on the remote host:

# /etc/ssh/sshd_config
AcceptEnv COLORTERM TERM_PROGRAM TERM_PROGRAM_VERSION

Then enable the client half with shell-integration-features = ssh-env. Without both sides, truecolor detection in some TUIs falls back to 256 colors.

Config that does not apply

Reload with cmd+shift+, on macOS or ctrl+shift+, on Linux, which runs the reload_config action. Quote nothing in the config file: font-family = "JetBrains Mono" keeps the quotes as part of the value, so write it bare.

ghostty +show-config --changes-only=false | grep font-family

Rendering and GPU issues

Blank windows, garbled glyphs, or heavy CPU use point at the renderer.

- Start clean to rule out your config: ghostty --config-default-files=false. - Turn off compositing effects first: background-blur, background-opacity below 1, and window-vsync. - Set font-thicken = false on macOS if text looks smeared, and remember font-thicken-strength only matters when thickening is on. - Linux with an unusual GPU stack: try forcing software rendering through the environment with LIBGL_ALWAYS_SOFTWARE=1 ghostty to confirm the GPU is at fault. - Check ghostty +version for the renderer and build mode before filing anything.

Ghostty 1.3.x uses Metal on macOS and OpenGL on Linux. A driver that cannot provide the required version fails at window creation, so the log is the place to look.

Keybinds not firing

1. Confirm the action name with ghostty +list-actions. An invalid action makes the whole keybind line invalid. 2. Confirm nothing else claims the trigger with ghostty +list-keybinds | grep cmd+k. 3. On macOS, system shortcuts and Spotlight win over the app. Check System Settings, Keyboard, Keyboard Shortcuts. 4. If a TUI needs a key Ghostty is eating, add keybind = ctrl+a=unbind to release it, or prefix with global: only when you actually want it to work app-wide. 5. option as alt on macOS is off by default. Set macos-option-as-alt = true for alt-based binds and for readline alt+f style motions.

Getting help with the right data

Include all of this in a bug report:

ghostty +version
ghostty +show-config
echo "$TERM · $COLORTERM · $TERM_PROGRAM_VERSION"

Plus the OS and version, the GPU on Linux, and a repro that starts from --config-default-files=false. Source, issues, and the discussion board are at github.com/ghostty-org/ghostty, and the option-by-option reference is at ghostty.org/docs/config/reference.