How to Use Ghostty: The Beginner's Guide

CodexFuse Team · 2026-10-30T12:59:24.677Z · 11 min read

Ghostty is a fast, free, GPU-accelerated terminal for macOS and Linux that works with zero config. This beginner guide covers install, the one config file, fonts and themes, splits, keybindings, and shell integration.

Learning how to use Ghostty is simpler than switching terminals usually is. Ghostty is a free, open-source, GPU-accelerated terminal emulator for macOS and Linux that works well the moment you install it — no config file required. This beginner's guide walks you from install to your first custom config: what you get with zero config, where the single config file lives (and the two-file gotcha on a Mac), how to set fonts and themes, the splits and keybindings you'll use every day, and how shell integration — including the new ghostty +ssh command in version 1.4 — just works.

Ghostty is the terminal app itself: the window your shell runs in. That makes it the natural companion to the other tools in our terminal cluster — the Neovim beginner guide (the editor that runs inside it), the tmux beginner guide (the multiplexer comparison), and the Warp beginner guide (the AI-terminal alternative).

What is Ghostty?

Ghostty is a fast, feature-rich terminal emulator for macOS and Linux created by Mitchell Hashimoto, the co-founder of HashiCorp, and released as open source in December 2024. Its core, libghostty, is written in Zig and renders with the GPU — Metal on macOS, OpenGL on Linux — while each platform gets a truly native app: Swift and AppKit on macOS, GTK4 with libadwaita on Linux. The project is free and MIT-licensed, and during the 1.3 development cycle it became a fiscally sponsored non-profit project through Hack Club.

Three ideas set Ghostty apart. First, it works with zero configuration: you get a good terminal the moment you install it. Second, the UI is genuinely native per platform — real macOS tabs and GTK windows, not a drawn-from-scratch interface. Third, everything you might want to change lives in one plain-text config file; there is no settings GUI and no scripting language to learn. The newest release, Ghostty 1.4.0 (October 27, 2026), adds scrollback compression that cuts memory use by 70–90%, a new ghostty +ssh command that fixes remote display glitches, and full coverage of the Kitty graphics specification.

How do I install Ghostty on Mac and Linux?

The short answer: on a Mac, install Ghostty with one Homebrew command; on Linux, install it from your distribution's package repository. Follow these steps:

1. macOS: run brew install --cask ghostty, or download the signed and notarized .dmg from ghostty.org/download and drag it into Applications.
2. Linux: install from your distro's repository — sudo pacman -S ghostty on Arch, sudo apt install ghostty on Ubuntu 26.04 and newer, a community COPR on Fedora, or sudo snap install ghostty --classic almost anywhere.
3. Verify: open Ghostty and run ghostty +version. You want 1.4.0 or newer.

On macOS, the Ghostty project ships the only official binaries: signed and notarized, universal (Apple Silicon and Intel), requiring macOS 13 or newer. Note that 1.3 is the last release series that supports macOS 13 — starting with 1.4 you need macOS 14. The Homebrew cask is community-maintained and merely repackages the official .dmg, so both install methods give you the same app at the same security level.

On Linux, the project itself distributes no binaries; packaging is done by distribution and community maintainers, and those packages are unaffiliated with the Ghostty project. The main routes are:

One requirement to check before installing 1.4 on Linux: it needs GTK 4.18 and libadwaita 1.7, up from 4.14/1.5. Ubuntu 24.04 LTS ships older versions, so on that LTS you should stay on an older Ghostty release or use the Flatpak — the 1.4 release notes say so explicitly.

What do you get with zero config on first launch?

A complete terminal. Ghostty ships sensible defaults, so a fresh install already gives you tabs, splits, a command palette, search in the scrollback, and native scrollbars — all with working default shortcuts. The project's own advice is to use it for a day with no config, then configure only the parts you miss.

The font is JetBrains Mono, which Ghostty embeds so it works even if you don't have it installed. The Nerd Fonts symbols are built in too, so prompts like Starship and tools like eza show their icons right away, with no patched font to install. Your terminal type is xterm-ghostty, and macOS Secure Input turns on automatically when you type a password.

Shell integration is injected automatically for bash, zsh, fish, and nushell. That means new tabs open in your current directory, the cursor becomes a bar at the prompt, and closing a tab at an idle prompt doesn't ask for confirmation. (Elvish users get a module they must load themselves.) These small behaviors are the "shell integration that just works" from this guide's title — and they work before you touch a single setting.

Where is the Ghostty config file — and why are there two on a Mac?

The location you should use is ~/.config/ghostty/config, on both macOS and Linux. Ghostty reads a plain-text file with one key = value pair per line and # comments — no Lua, no JSON, no nested blocks or indentation rules.

Here is the gotcha Mac users trip over: Ghostty also loads ~/Library/Application Support/com.mitchellh.ghostty/config. Both files are loaded, and the Application Support one wins. If you ever find your edits mysteriously ignored, check whether a second config exists in Application Support — keep the XDG one at ~/.config/ghostty/config and remove the duplicate. Teaching this once saves an hour of confused debugging later.

Working with the file is easy. Press Cmd+, on macOS (or Ctrl+, on Linux) to open it, or run ghostty +edit-config from any shell. After saving, reload with Cmd+Shift+, (macOS) or Ctrl+Shift+, (Linux) — no restart needed. Two handy actions while you're learning: ghostty +show-config prints your effective configuration, and ghostty +validate-config checks the file for errors. New in 1.4, ghostty +explain-config explains what any option does, right in the terminal.

How do I set fonts and themes in Ghostty?

Add font-family, font-size, and theme lines to your config file, then reload. A minimal starter config looks like this:

# ~/.config/ghostty/config
font-family = "JetBrains Mono"
font-size = 14
theme = "GitHub Dark"

To discover what's available, ask Ghostty itself: ghostty +list-fonts prints the exact family names installed on your system, and ghostty +list-themes lists every built-in theme you can drop into the theme line. Copy the family name exactly as +list-fonts reports it — font names are the most common reason a theme or font setting "doesn't work."

The add-only-what-you-use rule applies here: Ghostty's defaults are deliberately good, so change the font size first, add a theme second, and stop when you're happy. Custom themes go in ~/.config/ghostty/themes/ in Ghostty's own theme format if you ever outgrow the built-ins.

What are the Ghostty keybindings for splits and tabs?

Splits are built in — no tmux required. On a Mac, Cmd+D splits right and Cmd+Shift+D splits down; on Linux, Ctrl+Shift+O splits right and Ctrl+Shift+E splits down. New in 1.4 on Linux, you can also drag a split by its handle and drop it onto another split to rearrange your layout with the mouse.

These are the defaults you'll use every day. They work with no config, so learn them before changing anything:

Run ghostty +list-keybinds --default to print the complete list for your version, and rebind anything with keybind lines in your config — for example keybind = super+bracket_right=increase_font_size:1. One 1.4 change to know: on Linux, Ctrl+Shift+Page Up/Down now moves tabs instead of jumping to prompts, so check your muscle memory after upgrading.

How does Ghostty shell integration work?

Ghostty injects shell integration automatically for bash, zsh, fish, and nushell — you get prompt-aware features with no setup. New tabs and splits open in your current working directory, the cursor turns into a bar at the prompt, and you can jump between prompts with Cmd+Up/Down on macOS. On macOS it also adds the app's binary folder to your PATH, which is why ghostty +version works inside Ghostty but may need the full path (/Applications/Ghostty.app/Contents/MacOS/ghostty) from another terminal.

The classic remote-machine gotcha: servers that don't know Ghostty's terminfo show "missing or unsuitable terminal: xterm-ghostty", and programs like htop or nano misbehave. Version 1.4 fixes this with a drop-in SSH wrapper — just connect with:

ghostty +ssh user@server

It hands the server the terminal information it needs (installing terminfo and forwarding environment variables), falling back to a compatible setting if that fails. For everything else, plain ssh works as before.

Ghostty vs Warp vs iTerm2: which terminal should a beginner pick?

Pick Ghostty if you want a fast, native terminal that needs no config; pick Warp if you want AI built into the terminal; pick iTerm2 if you want the deepest macOS feature set and don't mind configuring it. Here's how they compare:

Two honest comparisons matter most for beginners. Against iTerm2, Ghostty covers the features most people actually use — splits, tabs, search, a quick terminal — with a fraction of the settings surface, but it's macOS-and-Linux only and younger. Against Alacritty, the difference is philosophy: Alacritty intentionally leaves managed tabs and splits to your window manager or a multiplexer like tmux, while Ghostty includes them.

And what about tmux itself? Ghostty's built-in splits replace tmux for local work — but tmux still wins when you need sessions that survive SSH disconnects or that you reattach from another machine. That's exactly when our tmux beginner guide earns its keep: run tmux inside Ghostty, and you get both.

Sources

• Ghostty official install docs — Binaries and Packages (install routes, macOS binaries, community cask): ghostty.org/docs/install/binary
• Flavio Copes, "A deep dive into Ghostty" (September 10, 2026; written against 1.3.1) — flaviocopes.com/ghostty/
• BitDoze, "Ghostty Terminal: Complete Mac Setup Guide (2026 Update)" — bitdoze.com/ghostty-terminal/
• BitDoze, "Starship + Ghostty: Ultimate Mac Terminal Setup Guide" — bitdoze.com/starship-ghostty-terminal/
• Linux und Ich, "Ghostty 1.4: Leaner Linux terminal with drag-and-drop splits" (October 28, 2026) — linuxundich.de/en/ghostty-1-4-linux-terminal/
• oflight, "Ghostty 1.4: New Features, 5.7x Faster & Upgrade Guide" (October 28, 2026; based on the official 1.4.0 release notes) — oflight.co.jp/en/columns/ghostty-1-4-release-features-upgrade-2026
• Gentoo Wiki, "Ghostty" (config file locations, +list-themes, CLI actions) — wiki.Gentoo.org/wiki/Ghostty
• Petronella Tech, "Ghostty Config Guide: Setup, Keybinds, Themes (2026)" — petronellatech.com/blog/ghostty-terminal-emulator-setup-configuration-guide-2026/

FAQ

Is Ghostty free?

Yes. Ghostty is free and open-source software under the MIT license. During the 1.3 development cycle it also became a fiscally sponsored non-profit project through Hack Club, so its funding model doesn't depend on selling you anything.

Does Ghostty work on Windows?

No official Windows version exists. It was on the long-term roadmap, but as of the 1.4 release the Windows GUI has been dropped from the roadmap — Windows users should stick with Windows Terminal or WezTerm.

Do I still need tmux if Ghostty has built-in splits?

For local work, usually not: Ghostty's tabs, splits, and command palette cover what most people used tmux for. Keep tmux for persistent remote sessions — ones that survive SSH disconnects and that you reattach from another machine — and run it inside Ghostty.

Where is the Ghostty config file on a Mac?

Use ~/.config/ghostty/config. Ghostty also loads ~/Library/Application Support/com.mitchellh.ghostty/config, and when both exist the Application Support one wins — so if your edits seem ignored, delete the duplicate and keep the XDG file.

How do I update Ghostty to 1.4?

On macOS run brew upgrade --cask ghostty (or replace the .dmg); on Linux use your package manager. Before upgrading, check the breaking changes: the copy-on-select default changed, scrollback-limit was renamed to scrollback-limit-bytes, and Linux now requires GTK 4.18 — Ubuntu 24.04 LTS should stay on 1.3.