Starship + Ghostty: Turbocharge Your Mac Terminal Setup

This guide walks through setting up Starship and Ghostty on your Mac. Together they make a solid Mac terminal setup: a GPU-accelerated terminal plus a prompt that shows Git status, language versions, and command duration. I’ll start with a Ghostty config, apply a Starship preset (Tokyo Night or Catppuccin Powerline), tune the prompt with a few lines of TOML, then add practical tools like zoxide and eza. I’ll also show you how to edit your ~/.zshrc without accidentally duplicating init lines, how to fix the failures that actually happen, and how to undo the whole thing cleanly.

If you want a Ghostty-first overview covering features, the inspector, and multiplexer vs tmux, check out Ghostty Terminal: A Complete Setup Guide for Modern Mac Development.

If you are going beyond prompt tweaks and want a terminal layout built around AI coding agents, browser automation, and notifications, I also wrote a dedicated guide to cmux Terminal.

TL;DR: Quick setup (copy/paste)

This is the fastest Mac terminal setup path: three brew commands, two lines in your shell config, one preset. Run these, then follow the sections below for the “why” and the optional upgrades:

brew install --cask ghostty
brew install starship zoxide eza
brew install font-meslo-lg-nerd-font

Add Starship and zoxide once to your ~/.zshrc:

open -e ~/.zshrc

Add:

eval "$(starship init zsh)"
eval "$(zoxide init zsh)"

Pick a Starship preset:

mkdir -p ~/.config
starship preset tokyo-night -o ~/.config/starship.toml
# or:
# starship preset catppuccin-powerline -o ~/.config/starship.toml

If a preset name errors out, run starship preset list to see the valid names for your installed Starship version. Names occasionally change between releases, and this is the most common failure in this whole guide.

Reload:

source ~/.zshrc

Verify: open a new Ghostty tab. If you see a themed powerline prompt, you’re done. If icons render as boxes, jump to Step 2 for the font fix. For everything else, keep reading.

Prerequisites

What you need before starting:

If Homebrew isn’t installed yet:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Cost note: every tool in this guide is free and open source, runs locally, and costs $0/month. No server, no subscription.

Why Ghostty and Starship?

Ghostty is a terminal emulator written in Zig. It uses GPU acceleration, works natively on macOS, and has a straightforward config system. You can learn more at ghostty.org.

Starship works with Zsh (the default macOS shell since Catalina) and other shells. It draws the prompt: Git status, directory paths, programming language versions, command duration. Presets and configuration live at starship.rs.

The pieces stack like this:

Each layer only talks to its neighbors. Ghostty runs Zsh, Zsh calls Starship to render each prompt, and the plugins and tools hook into Zsh directly. That separation is why this setup survives upgrades well: you can swap the terminal or the prompt without touching the rest.

If you’re comparing terminals before committing, we also have a WezTerm setup on Mac with tmux and zoxide. And if you later decide you want Ghostty-style rendering plus vertical workspaces, agent notifications, and a built-in browser, have a look at cmux.

Step 1: Install Ghostty on your Mac

Install Ghostty using Homebrew (see Prerequisites if you don’t have it yet):

brew install --cask ghostty

This installs Ghostty into your Applications folder.

Verify:

ghostty +version

You want a version string. If you get command not found, the Homebrew bin directory isn’t on your PATH (covered in Troubleshooting below).

Launch Ghostty from Applications or type ghostty in your current terminal. GPU acceleration makes it noticeably faster than older terminals. For other installation methods, visit ghostty.org/download.

Step 2: Install a Nerd Font

Starship’s powerline arrows and file icons use glyphs that stock macOS fonts don’t ship. Meslo Nerd Font works well and has clear icons.

Install it via Homebrew:

brew install font-meslo-lg-nerd-font

Check the font’s installation in Font Book by searching for “Meslo.” For other options, see nerdfonts.com.

ghostty +list-fonts | grep -i meslo

Step 3: Configure Ghostty

Create the config directory first (Ghostty won’t read a file that doesn’t exist):

mkdir -p ~/.config/ghostty
touch ~/.config/ghostty/config
open -e ~/.config/ghostty/config

Add this configuration:

font-family = MesloLGS Nerd Font Mono
font-size = 16
background-opacity = 0.85
theme = Argonaut

This sets MesloLGS Nerd Font Mono so powerline icons render cleanly, uses 16pt for readability, applies 85% background opacity, and selects the Argonaut theme. Two useful checks while you’re here:

ghostty +list-themes
ghostty +list-fonts

The first lists every theme name you can drop into the theme line. The second lists exact font family names.

Verify: press Cmd+Shift+, in Ghostty to reload the config without restarting. If something looks off, quit and reopen Ghostty; a full restart always applies the file.

Step 4: Install Starship

Starship adds contextual information to your prompt. Install it with Homebrew:

brew install starship

Integrate Starship with Zsh by adding it to your ~/.zshrc.

Instead of blindly appending with echo ... >> (which creates duplicates when you run the command twice), open your config and add the init line once:

open -e ~/.zshrc

Add:

eval "$(starship init zsh)"

Then reload:

source ~/.zshrc

Verify:

starship --version

The prompt also changes on reload, though it may look plain until you apply a preset in the next step. That’s expected. If you suspect you ran the init line more than once, check with grep -n starship ~/.zshrc and delete the extras. Duplicate init lines cause doubled prompts and a slower shell.

For other shells, see Starship’s installation guide.

Step 5: Apply a Starship preset

Presets are ready-made starship.toml files. Two popular options are Tokyo Night and Catppuccin Powerline. Browse all of them at starship.rs/presets.

cp ~/.config/starship.toml ~/.config/starship.toml.bak

mkdir -p ~/.config
starship preset tokyo-night -o ~/.config/starship.toml

open -e ~/.config/starship.toml

mkdir -p ~/.config
starship preset catppuccin-powerline -o ~/.config/starship.toml

Reload your shell with source ~/.zshrc to apply it.

If the preset command errors with an unknown name, run starship preset list for the valid names on your installed Starship version, then re-run the command with the corrected name.

Verify: your prompt should now show angled powerline segments with Git and directory info. If icons render as boxes instead, that’s a font problem, not a Starship problem. Go back to Step 2.

Step 6: Tweak your Starship config (starship.toml)

Presets are a good start, but a couple of changes usually make the prompt more practical: shorter paths, optional timestamps, and command duration for slow commands.

Open the config file:

open -e ~/.config/starship.toml

Paste these additions at the end. They work with both Tokyo Night and Catppuccin.

Recommended baseline tweaks

# Keep the prompt responsive if anything external is slow
command_timeout = 1000

[directory]
truncation_length = 3
truncate_to_repo = true

[cmd_duration]
min_time = 500
format = "took [$duration]($style) "
style = "yellow bold"

Reload:

source ~/.zshrc

What these do: command_timeout stops a slow module from hanging your prompt, truncation_length keeps deep paths to the last three directories, and cmd_duration shows how long any command over half a second took.

Optional: show time (useful in SSH sessions)

[time]
disabled = false
format = "[$time]($style) "
time_format = "%R"

Optional: show battery (laptops)

[battery]
disabled = false

Optional: Git status styling

If you want clearer Git signals:

[git_status]
style = "bold purple"

Optional: language versions

Enable Node.js when doing Node work:

[nodejs]
disabled = false

For the full list of modules and options, see Starship’s configuration documentation. Add modules one at a time to keep the prompt fast and readable.

When the prompt feels slow

Starship ships two diagnostic commands worth knowing:

starship timings
starship explain

starship timings shows how many milliseconds each module costs. starship explain shows what’s currently rendered and why. If one module dominates, disable it with a [module] section set to disabled = true, keep command_timeout set, and re-run starship timings to confirm.

Step 7: Install zoxide

zoxide learns your most frequently used directories and lets you jump to them with z instead of cd.

Install it:

brew install zoxide

Add it to your ~/.zshrc (open and edit, same rule as Starship: once, not appended):

open -e ~/.zshrc

Add:

eval "$(zoxide init zsh)"

Reload:

source ~/.zshrc

Use z instead of cd. For example, z proj jumps to your ~/Projects directory if you use it often. Zoxide ranks directories by frequency and recency, so it gets better the more you use it. For flags, shell init details, and advanced usage, see the complete Zoxide guide.

Step 8: Replace ls with eza

Note: eza is the modern replacement for ls (what people mean when they reference “exa” in older tutorials).

Swap the default ls command for eza to get colorized listings with file-type icons.

Install it:

brew install eza

Add aliases to your ~/.zshrc (add these once, don’t repeatedly append them):

open -e ~/.zshrc

Add:

alias ls="eza --icons"
alias ll="eza -l --icons"
alias la="eza -la --icons"

Reload:

source ~/.zshrc

These aliases:

• ls: Lists files with icons for file types
• ll: Shows a detailed list with icons
• la: Includes hidden files in the detailed list

Explore eza’s features at eza’s website.

Step 9: Add custom aliases

Aliases are worth adding for anything you type several times a day. These live in your ~/.zshrc.

Add these to ~/.zshrc:

# Quick edit configuration files
alias editstarship="vim ~/.config/starship.toml"
alias editghost="vim ~/.config/ghostty/config"

# Git shortcuts
alias gs="git status"
alias ga="git add"
alias gc="git commit -m"
alias gp="git push"

# Quick directory navigation
alias dev="cd ~/Development"
alias docs="cd ~/Documents"

Apply:

source ~/.zshrc

These aliases:

• Let you quickly edit Starship and Ghostty configs (editstarship, editghost)
• Simplify Git commands (gs, ga, gc, gp)
• Provide fast navigation to common directories (dev, docs)

Step 10: Add zsh-autosuggestions and zsh-syntax-highlighting

Add zsh-autosuggestions and zsh-syntax-highlighting for better command input and error detection.

Install:

brew install zsh-autosuggestions zsh-syntax-highlighting

Add to your ~/.zshrc (place syntax-highlighting near the end of the file, after other plugins, so it can color the suggestions too):

open -e ~/.zshrc

Add:

source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh
source $(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

Reload:

source ~/.zshrc

• zsh-autosuggestions: Suggests commands based on your history (gray text). Accept with the right arrow key.
• zsh-syntax-highlighting: Highlights valid commands in green and invalid ones in red, catching errors before execution.

For detailed setup, see Enable Command Autocomplete in Zsh and Enable Syntax Highlighting in Zsh. Want more? See our roundup of the best Oh My Zsh plugins.

Troubleshooting: common failure modes

These are the failures that actually come up with this stack, in the order you’re likely to hit them.

‘xterm-ghostty’: unknown terminal type

Some tools, mostly on remote servers, don’t recognize Ghostty’s terminal type. Fix it for the current session:

export TERM=xterm-256color

For a permanent solution, set this only for SSH so you don’t change behavior locally.

Add to your ~/.zshrc:

# Some servers don't know about Ghostty's TERM entry
if [[ -n "$SSH_CONNECTION" ]]; then
  export TERM=xterm-256color
fi

Reload:

source ~/.zshrc

Duplicated prompt or a slow shell

Symptom: the prompt renders twice, or every keystroke lags. Cause: multiple eval init lines, usually from re-running setup commands with >>.

Check:

grep -nE "starship|zoxide" ~/.zshrc

Fix: keep exactly one eval "$(starship init zsh)" and one eval "$(zoxide init zsh)", delete the rest, then source ~/.zshrc.

command not found: starship (or zoxide, or eza)

Cause: Homebrew’s bin directory isn’t on your PATH. Common on Apple Silicon, where Homebrew lives under /opt/homebrew.

Check:

which brew

If that prints nothing or points somewhere unexpected, make sure your ~/.zshrc contains:

eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Macs use /usr/local/bin/brew shellenv instead. This line must sit above the Starship and zoxide eval lines in the file.

Boxes instead of icons

Cause: the font-family string in your Ghostty config doesn’t match the installed font name.

Fix: run ghostty +list-fonts | grep -i meslo, copy the exact family name into font-family, then reload with Cmd+Shift+,. MesloLGS Nerd Font and MesloLGS Nerd Font Mono are both valid but different families; either works, as long as the string matches.

Preset command errors or your prompt looks default

Two causes. First, a preset name your Starship version doesn’t know: run starship preset list and use a name from that output. Second, the config file was never written: check with ls -la ~/.config/starship.toml. If it’s missing, re-run the preset command from Step 5. If the file exists but nothing changes, confirm eval "$(starship init zsh)" appears exactly once in ~/.zshrc.

Rollback: undo the whole setup

Nothing here is a one-way door. Tear it down in reverse order:

1. Remove the shell init lines. Open ~/.zshrc and delete the eval lines for Starship and zoxide, the plugin source lines, and any aliases you added:

open -e ~/.zshrc

2. Delete the config files:

rm ~/.config/starship.toml
rm -rf ~/.config/ghostty

If you made the backup in Step 5, keep starship.toml.bak.

3. Uninstall the packages. Ghostty and the font are casks, the rest are formulae, so two commands:

brew uninstall --cask ghostty font-meslo-lg-nerd-font
brew uninstall starship zoxide eza zsh-autosuggestions zsh-syntax-highlighting

One note: zoxide’s directory database lives at ~/.local/share/zoxide and survives uninstall. Leave it if you might come back, or delete it for a fully clean slate.

Verify: open a new terminal window. You should see the default macOS prompt and a clean startup with no errors.

FAQ

Conclusion

Your Mac terminal now has Ghostty and Starship, a Starship preset you like, minimal tweaks, and practical tools like zoxide, eza, and sensible aliases. Total cost: $0/month, all local.

Next steps:

• Explore Ghostty capabilities (themes, inspector, shaders) in Ghostty Terminal: A Complete Setup Guide for Modern Mac Development
• Keep your Starship config lean by adding modules only when you need them
• Browse Starship’s preset gallery when you want a different look

If you’re interested in using Starship with Fish Shell instead of Zsh, I have a dedicated guide: How to set up Starship prompt with Fish Shell. Also see Fish Shell vs Zsh if you’re considering switching shells.

And if you record your terminal for tutorials or demos, I use Screen Studio for polished macOS screen recordings.