Ghostty Terminal: A Complete Setup Guide for Modern Mac Development

Ghostty is a modern, GPU-accelerated terminal emulator that’s quickly gaining popularity among developers and power users. It’s fast, native-feeling on macOS, and straightforward to configure. Its rendering engine, libghostty, is also powering a fast-growing ecosystem of new terminals — cmux and 100+ others.

In this guide you’ll:

• Install Ghostty and a Nerd Font (so icons render correctly)
• Set up a clean ~/.config/ghostty/config
• Learn the standout Ghostty features (themes, inspector, shaders, image support)
• Understand the libghostty ecosystem: cmux and 100+ other terminals built on Ghostty’s engine
• (Optional) Layer in a modern prompt and productivity tools like tmux and zoxide

If you specifically want Starship + Ghostty with presets and a complete prompt setup, see my companion guide: Turbocharge Your Mac Terminal: The Ultimate Starship and Ghostty Setup Guide: https://www.bitdoze.com/starship-ghostty-terminal/

Key Features of Ghostty

GPU Acceleration

Ghostty renders using your GPU, which means fast scrolling and smooth performance. Complex terminal output stays responsive, and working with large files doesn’t slow things down.

Native UI

Ghostty doesn’t try to be a one-size-fits-all UI. On macOS it uses native Swift and AppKit, on Linux it uses GTK4. Because of this, Ghostty actually feels like part of your system instead of a foreign tool.

Simple Configuration File (Key-Value)

Config is straightforward: ~/.config/ghostty/config uses simple key-value pairs. No scripting language, no complex syntax. Change fonts, pick a theme, adjust opacity.

Built-in Multiplexer

Ghostty has built-in multiplexing so you can split panes and manage multiple sessions without reaching for tmux. If you want to take that idea further for AI workflows, with agent notifications, vertical workspaces, and a built-in browser, see my guide to cmux terminal.

Rich Color Support

Supports true color and comes with over 100 themes built-in. You can also add custom ones if you prefer something specific.

Image Support

Ghostty supports the Kitty Graphics Protocol, so you can render images directly in the terminal. Useful if you work with preview tools or want visual output inline.

What’s New in Ghostty 1.3 (March 2026)

Ghostty 1.3.0 shipped on March 9, 2026, with 6 months of work and 180 contributors. The current release is 1.3.1. Here are the headline features:

• Scrollback search — Cmd+F on macOS or Ctrl+Shift+F on GTK to search your terminal history. All matches highlighted, navigate with arrow keys. The search bar can be dragged to any corner on macOS.
• Native scrollbars — scrollbars now look and behave like your OS expects. They appear during scrolling and fade out when idle.
• Click to move cursor — if your shell supports OSC 133 prompt detection, you can click to position the cursor in your prompt. Works with zsh, fish, and bash with the right prompt setup.
• Key overlay for leader keys — a visual overlay appears after pressing a leader key showing available bindings. Useful if you use custom keybindings or tmux prefix keys.
• Auto-update on macOS — Ghostty can now update itself without needing Homebrew or a manual download. Includes delta patching to keep updates small.
• Text shaping improvements — better handling of complex scripts (Arabic, Devanagari, Thai) and ligatures.
• Security fix — CVE-2026-26982 patched an issue where control characters in pasted text could execute commands. Update to 1.3.1 if you haven’t already.

To update if you installed via Homebrew:

brew upgrade --cask ghostty

Ghostty is on a 6-month release cadence, so the next minor release, 1.4.0, is planned for September 2026. The project is now backed by a non-profit organization, and the macOS app sees roughly a million downloads a week. There are no signs of it slowing down.

Performance

Ghostty’s written in Zig, which shows in the performance. Benchmarks consistently put it among the fastest terminals for handling large Unicode files.

Keep in mind: benchmarks depend heavily on your setup (font, shaders, opacity) and the workload being tested. Real-world differences are smaller than numbers suggest.

Terminal	Version	Speed
Ghostty	1.3	73ms
Alacritty	0.13	66ms
WezTerm	20240203	140ms

Unique Features

Terminal Inspector

The Terminal Inspector is one of Ghostty’s best features. It shows you real-time debugging info—keystrokes, render timings, everything happening under the hood. Handy if you’re troubleshooting or just curious about what’s going on.

Shaders

You can write custom shaders to apply visual effects—think glow effects, CRT filters, or whatever else you want to try. Fun if you like tweaking things visually.

The libghostty Ecosystem: A Terminal Library, Not Just a Terminal

Everything above describes Ghostty the app. Since late 2025 there’s a second, arguably bigger story: libghostty. It’s the cross-platform, C-ABI-compatible library (written in Zig) that powers Ghostty itself — terminal emulation, font handling, and rendering — and any application can embed it. Think of it like WebKit for terminals: the Ghostty GUI is just one consumer of the engine.

Mitchell Hashimoto announced libghostty in September 2025, starting with libghostty-vt, a zero-dependency library that parses terminal sequences and maintains terminal state. The ecosystem grew faster than anyone expected.

The awesome-libghostty list already tracks more than 100 projects built on the engine. The most interesting ones:

Project	Platform	What it adds
cmux	macOS	Vertical tabs, notification rings when agents need input, in-app scriptable browser, CLI/socket API
blink, Zentty, Forge, in0, Supacode	macOS	Agent-centric workspaces: live session status, worktrees, orchestration
Muxy, ykmx, it-shell3	macOS	Terminal multiplexers on the libghostty core
Enso, macterm, justty	macOS	Different takes on a lightweight native Ghostty terminal
Echo, Geistty, Spectty	iOS/iPadOS	SSH/Mosh clients with Ghostty rendering
Umbra	Android	GPU-accelerated Android terminal
mightty, phantty	Windows	Experimental Windows ports and renderers
deepin-terminal-ghostty, Husk, forgetty	Linux	GTK/Wayland terminals on the Ghostty core
OrbStack	macOS	Ghostty-powered terminal inside its Docker/Linux VM app
vscode-bootty	VS Code	libghostty terminal inside VS Code
obsidian-ghostty-terminal	Obsidian	Real terminal in your notes
Godotty	Godot Engine	Terminal emulator for the game engine
ghostty-web, browstty	Browser	Ghostty compiled to WebAssembly, running in a web page

There are also bindings for Rust, Go, .NET, Python, TypeScript, Flutter/Dart, Elixir, Odin, C++, MoonBit, and HarmonyOS — building a custom terminal is now a weekend project instead of a multi-year one.

Why this matters to you

Your Ghostty config is portable. cmux, by far the most popular libghostty app (18k+ GitHub stars), reads your existing ~/.config/ghostty/config for themes, fonts, and colors — you get a completely different app with zero reconfiguration. I have a full guide here: cmux Terminal: A Practical Guide for AI Coding Agents on macOS.

More importantly, terminals are no longer forced to be generic. Keep Ghostty as your daily driver and run a specialized app (an agent workspace, an SSH client, an embedded terminal) when the job calls for it — without relearning rendering quirks, config syntax, or fonts. Every libghostty app inherits the same correctness and performance.

Further reading: ghostty.org/docs/about · libghostty announcement · awesome-libghostty

Installation and Configuration

If you are interested to see some free cool Mac Apps you can check toolhunt.net mac apps section.

Quickstart (TL;DR)

Quick setup if you just want Ghostty running:

brew install --cask ghostty
brew install font-meslo-lg-nerd-font
mkdir -p ~/.config/ghostty

Then create ~/.config/ghostty/config with the basic config below and restart Ghostty.

Ghostty Install

Download Ghostty directly or use Homebrew:

brew install --cask ghostty

Ghostty on Linux

Ghostty is packaged in Ubuntu 26.04 LTS (universe repo, amd64 + arm64) as a preview:

sudo apt install ghostty

The packaged version tracks upstream (1.3.x), and GPU acceleration requires OpenGL 4.3+. On machines without it — older GPUs, some Raspberry Pi setups — Ghostty falls back to software rendering:

LIBGL_ALWAYS_SOFTWARE=true ghostty

libghostty itself isn’t packaged yet, but the Ubuntu maintainers plan to ship it as a separate binary package.

Install Meslo Nerd Font

Nerd Fonts include programming icons and symbols. Install Meslo LG via Homebrew:

brew install font-meslo-lg-nerd-font

The font installs automatically. Verify it in Font Book if needed. You may need to restart Ghostty after installation.

Setup Ghostty Config File

Create the config file and add basic settings:

mkdir -p ~/.config/ghostty
vim ~/.config/ghostty/config

Add this to the config:

font-family = MesloLGS Nerd Font Mono
font-size = 18
background-opacity = 0.9
theme = Argonaut

Find available fonts and themes:

ghostty +list-fonts
ghostty +list-themes

Restart Ghostty after saving. If icons look broken, verify that Ghostty is using the Nerd Font you installed.

Tip: Keep your Ghostty config minimal—put heavy customization in your shell rc files or prompt setup instead. This makes it easier to sync across machines.

More settings worth trying

The basic config gets you running. These options cover the most-requested tweaks:

Option	Example	What it does
window-padding-x / window-padding-y	window-padding-x = 12	Breathing room around your text
cursor-style	cursor-style = bar	Bar, block, or underline cursor
copy-on-select	copy-on-select = true	Copy immediately when you select text
mouse-hide-while-typing	mouse-hide-while-typing = true	Hide the mouse cursor while you type
background-blur-radius	background-blur-radius = 20	Blur behind transparency (macOS)
confirm-close-surface	confirm-close-surface = false	Skip the close confirmation dialog
shell-integration-features	shell-integration-features = true	OSC 133 marks: enables click-to-move-cursor and prompt jumping
keybind	keybind = global:cmd+backquote=toggle_quick_terminal	Drop-down “Quake” terminal from anywhere

Essential shortcuts (macOS defaults)

Action	Shortcut
New tab	Cmd+T
New split (right / down)	Cmd+D / Cmd+Shift+D
Close surface	Cmd+W
Toggle fullscreen	Cmd+Enter or Cmd+Ctrl+F
Scrollback search	Cmd+F
Terminal inspector	Cmd+Option+I
Increase / decrease font size	Cmd+= / Cmd+-
Open / reload config	Cmd+, / Cmd+Shift+,

All of these are rebindable with keybind lines — run ghostty +list-keybinds --default to see your current defaults.

Prompt Options (Pick One)

Now you need a prompt. Pick one:

• Starship: Works with any shell, has ready-made themes, and is fast. I have a full guide for Starship + Ghostty: https://www.bitdoze.com/starship-ghostty-terminal/
• Powerlevel10k: Built for zsh, highly configurable, popular with zsh users.

Install powerlevel10k theme

Install Powerlevel10k:

brew install powerlevel10k
echo "source $(brew --prefix)/share/powerlevel10k/powerlevel10k.zsh-theme" >> ~/.zshrc
source ~/.zshrc

The first run shows a configuration wizard. Walk through it to customize your prompt—choose what segments to display, colors, icons, etc. You can always rerun p10k configure later to tweak it.

The result is a prompt that shows git status, command execution time, and more, without sacrificing speed. Edit ~/.p10k.zsh if you want to fine-tune it further.

Setup zsh-autosuggestions plugin

zsh-autosuggestions suggests commands as you type, based on your history. Get it working:

brew install zsh-autosuggestions
echo "source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh" >> ~/.zshrc
source ~/.zshrc

Now when you type, you’ll see faded suggestions. Press the right arrow or End to accept them. You can customize the suggestions in .zshrc—change colors, tweak keybindings, etc.

See also: Enable Command Autocomplete in Zsh

Setup zsh-syntax-highlighting

zsh-syntax-highlighting colors your commands as you type—green for valid commands, red for errors. Install it:

brew install zsh-syntax-highlighting
echo "source $(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ~/.zshrc
source ~/.zshrc

It highlights valid commands and options, underlines existing file paths, and matches bracket pairs. Catch typos before you hit enter.

See also: Enable Syntax Highlighting in Zsh

Enhance Ghostty with tmux and zoxide

Ghostty has built-in multiplexing, but tmux is worth adding if you need:

• Remote attach/detach workflows over SSH
• Session sharing across machines or teams
• A larger ecosystem and documentation

If your workflow is more local and agent-heavy than remote, cmux is another route worth looking at — it’s the flagship of the libghostty ecosystem I covered above. I have a full setup guide here: cmux Terminal: A Practical Guide for AI Coding Agents on macOS.

zoxide makes jumping between directories faster.

What is tmux and how can it help

tmux lets you manage multiple terminal sessions in one window. Useful for running background processes, sharing sessions with others, or keeping your setup across reboots.

brew install tmux

Then just type tmux to start a new session. More details: Tmux Basics

What is zoxide and how can it help

zoxide replaces cd with smarter navigation. It tracks your most-used directories so you can jump to them quickly with fuzzy matching.

brew install zoxide
echo 'eval "$(zoxide init zsh)"' >> ~/.zshrc
source ~/.zshrc

Now use z instead of cd to jump around. See: Zoxide Guide

With tmux, zoxide, and Ghostty together, you’ve got a solid terminal workflow—multiplexing, fast navigation, and GPU-powered rendering.

Known Ghostty Errors

‘xterm-ghostty’: unknown terminal type

On some remote Linux machines, tools may not recognize Ghostty’s terminal type and you can see errors like: 'xterm-ghostty': unknown terminal type.

Quick fix for the current session:

export TERM=xterm-256color

Permanent fix on that machine:

echo "export TERM=xterm-256color" >> ~/.bashrc
source ~/.bashrc

If it only happens over SSH, set TERM conditionally in your shell config instead.

Conclusion

Ghostty feels like a terminal built for 2026. GPU rendering, native UI, the Inspector—it’s a step above what most terminals offer. And with libghostty, it’s quietly becoming the engine for the next generation of terminals: specialized, agent-aware, and embedded everywhere. Ghostty 1.4 lands in September 2026, and Hashimoto’s prediction is that by mid-2027 more people will use Ghostty through libghostty apps than the GUI itself.

If you spend time in the terminal, give Ghostty a try — and if you run AI coding agents, cmux is worth adding on top. The setup is straightforward, and once configured, you’ve got a fast, responsive terminal that doesn’t get in your way.

Ghostty works great with Fish Shell too. If you’re looking for a shell upgrade, see my Fish Shell vs Bash vs Zsh comparison or set up Starship prompt with Fish.