Ghostty Docs Quick Read: Installation, Configuration, and Daily Usage Notes

Fri, 15 May 2026 14:50:11 +0800

Ghostty is a new terminal emulator, but it is not simply “another faster terminal.” According to its official documentation, it tries to balance three goals at the same time: speed, features, and a native desktop experience. In other words, it wants GPU acceleration and solid rendering performance, while also feeling like a real local app on macOS and Linux instead of pushing every interaction into a custom-drawn interface.

If you currently use iTerm2, Kitty, Alacritty, WezTerm, or the system terminal, the most interesting part of Ghostty is not one isolated feature. It is the way it combines “works out of the box” with “deeply configurable.” The default configuration is already usable, but when you want to tune it further, the docs provide complete entry points for configuration files, themes, keybindings, fonts, Shell integration, and terminal control sequences.

Start with the Positioning

Ghostty’s core positioning can be summarized in three points:

It is a cross-platform terminal emulator, currently focused on macOS and Linux.
It uses platform-native UI: Swift, AppKit, and SwiftUI on macOS; Zig and GTK4 on Linux.
Its terminal core is libghostty, and the GUI applications are built around this shared core.

This design affects daily use. Tabs, splits, error prompts, window state restoration, system shortcuts, and similar features are not merely components that “look like a desktop app.” They try to follow the interaction conventions of each operating system. The default shortcuts on macOS and Linux also differ according to platform expectations.

Installation: Direct on macOS, Distribution-Dependent on Linux

The official prebuilt binaries mainly target macOS. The most common installation path is to download the .dmg, open it, and drag Ghostty into the Applications folder. Homebrew users can also use the community-maintained cask:

`1`	`brew install --cask ghostty`

Linux is more fragmented. The Ghostty docs separate package managers, community binaries, and source builds for different distributions. Arch, Alpine, Gentoo, NixOS, Snap, Solus, Void, and others all have their own paths. If a distribution has no official or trusted repository, the docs lean toward building from source rather than casually installing third-party binaries.

This matters especially on servers and workstations: a terminal emulator handles a large amount of input and output, clipboard data, links, SSH sessions, and local file paths. It is better to be conservative with the installation source, preferring the official macOS package, distribution repositories, or a build process whose source you can audit.

Configuration: Do Not Rush to Copy a Giant dotfiles Setup

Ghostty’s configuration philosophy is “usable with zero configuration.” The default font includes JetBrains Mono and Nerd Font support, so most users can work normally the first time they open it. The docs even suggest that if you must configure a non-subjective option to feel comfortable, it may be worth asking whether that behavior should become the default.

When you do need customization, Ghostty uses a text configuration file. The current configuration file name is config.ghostty, while older versions also support config. Common paths include:

$XDG_CONFIG_HOME/ghostty/config.ghostty
$XDG_CONFIG_HOME/ghostty/config
$HOME/.config/ghostty/config.ghostty
$HOME/.config/ghostty/config

On macOS, Ghostty also reads:

1
2

$HOME/Library/Application Support/com.mitchellh.ghostty/config.ghostty
$HOME/Library/Application Support/com.mitchellh.ghostty/config

The syntax is straightforward: key = value. For example:

font-family = JetBrains Mono
font-size = 14
theme = light:Rose Pine Dawn,dark:Rose Pine
keybind = ctrl+shift+t=new_tab

A practical suggestion: do not start by copying someone else’s full configuration. A steadier approach is to run it bare for a few days and change only three things at first: font family, font size, and theme. Once you actually feel friction around shortcuts, splits, windows, or Shell integration, add those settings one by one.

Documentation Lookup: Full Configuration Reference Is Available Locally

Ghostty has many configuration options, and the official docs collect them in the Option Reference. Besides the web page, you can query the reference locally after installation:

`1`	`ghostty +show-config --default --docs`

This command prints the default configuration and documentation to standard output, which is useful when piped into a pager:

`1`	`ghostty +show-config --default --docs \| less`

To list available fonts:

`1`	`ghostty +list-fonts`

To list built-in and available themes:

`1`	`ghostty +list-themes`

To view default keybindings:

`1`	`ghostty +list-keybinds --default`

These commands are more reliable than copying snippets from the web, because they come from the Ghostty version installed on your own machine.

Keybindings: Treat “Actions” as the Core Concept

Ghostty’s keybinding format is:

`1`	`keybind = trigger=action`

trigger is the key sequence, and action is the operation Ghostty performs. Creating a new tab, closing the current surface, reloading configuration, and jumping to a prompt are all actions. The model is clear: you are not “changing a menu item”; you are binding an input sequence to an action.

After changing configuration, you can reload it at runtime. The default shortcut is:

Linux: ctrl+shift+,
macOS: cmd+shift+,

Not every setting takes effect immediately. Some options only affect newly created terminals, while others require a full restart. If “the config is written but nothing changed,” check the documentation for that option before spending too much time suspecting syntax.

Themes and Fonts: Use Built-Ins First, Then Tune

Ghostty ships with many themes and supports switching themes according to the system light or dark mode:

`1`	`theme = light:Rose Pine Dawn,dark:Rose Pine`

Themes can also come from custom files. The docs are clear here: a theme file is essentially a Ghostty configuration file and can set many options, so do not casually use themes from untrusted sources.

For fonts, font-family can be repeated to specify fallback fonts. This is useful in multilingual environments: the primary font can handle English and symbols, while later fonts cover Chinese, Japanese, or other characters. When you encounter display details such as emoji, bold, italic, or ligatures, look up the corresponding options in the Option Reference.

Shell Integration: Especially Important for SSH Users

Ghostty supports automatic Shell integration injection for bash, elvish, fish, nushell, and zsh. When enabled, several interactions become more natural:

New terminals can open in the previous terminal’s working directory.
Complex prompts can redraw correctly after resize instead of reflowing badly.
You can jump between command outputs using prompt markers.
Cursor behavior at the prompt can better match editing habits.

If you do not want automatic injection, disable it in the configuration:

`1`	`shell-integration = none`

SSH deserves extra attention. Ghostty uses xterm-ghostty as TERM, but many remote hosts do not yet have the corresponding terminfo. The docs provide two Shell integration features, ssh-env and ssh-terminfo, which are disabled by default and can be enabled as needed:

`1`	`shell-integration-features = ssh-env,ssh-terminfo`

If you often connect to old servers, containers, bastion hosts, or tightly managed production environments, read the official Terminfo and Shell Integration docs before enabling these features. Terminal capability negotiation looks minor, but when it goes wrong, the symptoms can be strange colors, broken shortcuts, or garbled full-screen programs.

My Suggested Onboarding Order

If you only want to judge whether Ghostty fits you, try this sequence:

Install it and use it for a day without writing any configuration.
Adjust only font-family, font-size, and theme.
Use ghostty +list-keybinds --default to inspect default shortcuts instead of importing someone else’s shortcut table first.
If you use SSH often, check remote host terminfo compatibility early.
Finally, tune splits, windows, transparency, title bar, background image, and other visual or workflow preferences.

Ghostty’s docs are engineering-oriented. They are better read as a configuration reference manual than as a marketing page. For most users, the real evaluation criteria are simple: does the default experience already feel comfortable, and are your daily editor, Shell, SSH, tmux, or Zellij workflows stable? If those pieces work well, Ghostty deserves a place on your long-term terminal shortlist.

Terminal Emulator on KnightLi Blog