Skip to main content

​
Installing Ghostty

Ghostty is available for macOS and Linux. Choose your platform below to get started.
Ghostty requires modern system versions and specific dependencies. Make sure to review the requirements for your platform before installing.

​
Platform Installation

​
macOS Installation

Ghostty is a native SwiftUI application for macOS with Metal rendering support.

​
Requirements

  • macOS 13 (Ventura) or later
  • Apple Silicon (M1/M2/M3) or Intel Mac

​
Download Official Release

The easiest way to install Ghostty is to download the official release:

Download for macOS

Get the latest official release from the Ghostty website
  1. Download the .dmg file from the official website
  2. Open the downloaded file
  3. Drag Ghostty to your Applications folder
  4. Launch Ghostty from Applications
On first launch, you may need to right-click and select “Open” to bypass Gatekeeper security warnings.

​
Install via Homebrew

# Install the latest release
brew install --cask ghostty

​
Install via MacPorts

sudo port install ghostty

​
Verify Installation

# Check version
ghostty --version

# Launch Ghostty
open -a Ghostty

​
Building from Source

Building Ghostty from source gives you the latest features and allows you to customize the build.
Building from source requires more technical knowledge and additional dependencies compared to binary installation.

​
Prerequisites

Ghostty requires specific versions of build tools: 
# Ghostty requires Zig 0.14.0 or later
# Download from https://ziglang.org/download/

# Verify installation
zig version

​
Build Process

1

Clone the Repository

git clone https://github.com/ghostty-org/ghostty
cd ghostty
2

Build Ghostty

# Debug build (default, faster compilation)
zig build

# Release build (optimized, recommended for daily use)
zig build -Doptimize=ReleaseFast
The first build will download dependencies and may take several minutes.
3

Install (Optional)

# Install to /usr/local (requires sudo)
sudo zig build --prefix /usr/local -Doptimize=ReleaseFast

# Or install to custom location
zig build --prefix ~/.local -Doptimize=ReleaseFast
4

Run Ghostty

# Run directly from build directory
zig build run

# Or run installed binary
ghostty

​
Build Options

Ghostty supports several build configurations: 
# See all build options
zig build --help

# Common options:
zig build -Doptimize=ReleaseFast     # Optimized release
zig build -Doptimize=Debug            # Debug symbols
zig build -Dcpu=baseline              # Generic CPU (no AVX)
zig build test                        # Run unit tests
zig build run                         # Build and run
For more detailed build instructions, see the Building from Source Guide and HACKING.md.

​
Packaging for Distribution

If you’re packaging Ghostty for a Linux distribution:

​
Source Tarballs

Official source tarballs with stable checksums are available: 
# Download release tarball
wget https://release.files.ghostty.org/<VERSION>/ghostty-<VERSION>.tar.gz
wget https://release.files.ghostty.org/<VERSION>/ghostty-<VERSION>.tar.gz.minisig

# Verify signature with minisign
minisign -Vm ghostty-<VERSION>.tar.gz \
  -P RWQlAjJC23149WL2sEpT/l0QKy7hMIFhYdQOFy0Z7z7PbneUgvlsnYcV

​
Build for System Package

# Fetch dependencies offline
ZIG_GLOBAL_CACHE_DIR=/tmp/offline-cache \
  ./nix/build-support/fetch-zig-cache.sh

# Build with system paths
DESTDIR=/tmp/ghostty \
zig build \
  --prefix /usr \
  --system /tmp/offline-cache/p \
  -Doptimize=ReleaseFast \
  -Dcpu=baseline
See PACKAGING.md for complete packaging guidelines.

​
Post-Installation

After installing Ghostty:

​
Set as Default Terminal

  1. Open System Settings > Privacy & Security
  2. Scroll to Automation
  3. Enable Ghostty access if needed
  4. Set Ghostty as default in Terminal preferences

​
Create Configuration

Create your first config file: 
# Create config directory
mkdir -p ~/.config/ghostty

# Create config file
touch ~/.config/ghostty/config

# Edit with your favorite editor
vi ~/.config/ghostty/config
Add some basic settings: 
# ~/.config/ghostty/config
font-family = "JetBrains Mono"
font-size = 13
theme = catppuccin-mocha

​
Enable Shell Integration

Set up shell integration for enhanced features: 
# Bash - add to ~/.bashrc
if [ -n "$GHOSTTY_RESOURCES_DIR" ]; then
    source "$GHOSTTY_RESOURCES_DIR/shell-integration/bash/ghostty.bash"
fi

# Zsh - add to ~/.zshrc
if [ -n "$GHOSTTY_RESOURCES_DIR" ]; then
    source "$GHOSTTY_RESOURCES_DIR/shell-integration/zsh/ghostty.zsh"
fi

​
Troubleshooting

​
Common Issues

Check dependencies:
# Linux - verify GTK installation
pkg-config --modversion gtk4

# Should return >= 4.12.0
Check logs:
# macOS
sudo log stream --level debug --predicate 'subsystem=="com.mitchellh.ghostty"'

# Linux
journalctl --user --unit app-com.mitchellh.ghostty.service
Verify Zig version:
# Check required version in build.zig
grep required_zig build.zig

# Your version
zig version
Ghostty requires exact Zig versions. Download the correct version from ziglang.org.
Refresh font cache:
# Linux
fc-cache -fv

# List available fonts
ghostty +list-fonts
Remove quarantine attribute:
xattr -cr /Applications/Ghostty.app
Or right-click Ghostty in Applications and select “Open”.

​
Getting Help

If you encounter issues:
  1. Check the Troubleshooting Guide
  2. Search existing issues
  3. Review HACKING.md for development setup
  4. Ask in GitHub Discussions

​
Next Steps

Quick Start

Learn the basics and configure your first setup

Configuration

Explore all configuration options

Building from Source

Detailed guide for building Ghostty yourself

Contributing

Help improve Ghostty