Frequently-asked questions

[pluiedev]

Please make sure you've read through all of these FAQs before opening a new post!

Any problem with xterm-ghostty

Please read through https://ghostty.org/docs/help/terminfo thoroughly.

Can't copy/cut/paste (Cmd+C/X/V) from the search bar on macOS

See #10749.

Unable to type special characters, wrong characters are typed, compose keys not working, key modifiers not working, etc. on Linux

Please make sure your issue is different from #8899. Doubly so if you just installed a major update to your system.

Otherwise, check out the list of reported problems at #8910.

Severe tearing/flickering with TUI apps like Claude Code, Docker, Ollama, etc.

See https://ghostty.org/docs/help/synchronized-output. TL;DR Ghostty is rendering much more quickly than these apps update the visible area, and the apps need to implement a protocol to tell Ghostty to slow down.

Crashes/blackscreens/"unable to acquire OpenGL context" on startup

Warning

If you installed Ghostty with Nix on a non-NixOS system, please make sure to read https://ghostty.org/docs/install/binary#nix-on-other-distros beforehand. This is the most likely reason for this problem, and is an unavoidable side effect of how Nix works.

Your graphics driver cannot be found, is malfunctioning, or is too old. On Linux, Ghostty requires OpenGL 4.3 or later — we do intend to implement a software renderer in the future to make Ghostty run more smoothly in virtual machines and old PCs. See #6073 for more information.

Tabs appear as separate windows on macOS

With the tab system built into macOS, tabs are windows that are simply stitched together by the compositor and UI decorations. This is exactly how Apple designed them to work, which is why each tab shows up as a separate window in the Dock's context menu, or in window managers like Aerospace and Yabai. Other native macOS apps like Finder and Preview behave similarly.

There is a list of workarounds in https://ghostty.org/docs/help/macos-tiling-wms, but we will eventually add a custom tabbing solution that avoids this problem entirely (much like what Apple themselves did with apps like Safari).

See #5880.

Cryptic compilation errors (e.g. "error: expected string literal")

Please make sure you are using the correct version of the Zig compiler your Ghostty version needs. Zig is an unstable, pre-1.0 language whose newest compiler might not always be able to compile older code.

The table of Zig compilers that each Ghostty version needs can be found on our website, under "Build Ghostty from Source".

Also see #6732.