Installation

Install Ghostty on macOS, Linux, or build from source

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

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

Homebrew Cask

# Install the latest release
brew install --cask ghostty

# Build from source via Homebrew
brew install ghostty

Install via MacPorts

sudo port install ghostty

Verify Installation

# Check version
ghostty --version

# Launch Ghostty
open -a Ghostty

Linux

Linux Installation

Ghostty uses GTK for its Linux application interface with OpenGL rendering.

Requirements

• GTK 4 (version 4.12 or later recommended)
• libadwaita
• OpenGL support
• A relatively recent Linux distribution

Install via Package Manager

Ghostty is available in several Linux distribution repositories:

Arch Linux (AUR)

# Using yay
yay -S ghostty

# Or using paru
paru -S ghostty

# Git version
yay -S ghostty-git

# Install from Copr
sudo dnf copr enable pgdev/ghostty
sudo dnf install ghostty

# Add PPA (if available) or build from source
# Check https://ghostty.org/download for latest packages

# Install with nix profile
nix profile install nixpkgs#ghostty

# Or add to configuration.nix
environment.systemPackages = [ pkgs.ghostty ];

# Install from Flathub
flatpak install flathub org.mitchellh.ghostty

# Run Ghostty
flatpak run org.mitchellh.ghostty

Package availability varies by distribution. Check the official download page for the most up-to-date installation methods.

Install from Binary

Download pre-built binaries from the releases page:

# Download latest release
wget https://release.files.ghostty.org/<VERSION>/ghostty-<VERSION>.tar.gz

# Extract
tar -xzf ghostty-<VERSION>.tar.gz

# Install (requires sudo)
cd ghostty-<VERSION>
sudo cp bin/ghostty /usr/local/bin/

Verify Installation

# Check version
ghostty --version

# Launch Ghostty
ghostty

FreeBSD

FreeBSD Installation

Ghostty supports FreeBSD using the GTK application runtime.

Requirements

• FreeBSD 13 or later
• GTK 4 and libadwaita
• OpenGL support

Install via Ports

# Install from ports
cd /usr/ports/x11/ghostty
make install clean

Install via pkg

# Install binary package
pkg install ghostty

Build from Source

See the Building from Source guide for detailed instructions.

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:

Zig Compiler

# Ghostty requires Zig 0.14.0 or later
# Download from https://ziglang.org/download/

# Verify installation
zig version

# Xcode 16 or later (for macOS 16 SDK)
# Check Xcode version
xcodebuild -version

# Select correct Xcode
sudo xcode-select --switch /Applications/Xcode.app

# Install build dependencies
sudo apt-get update
sudo apt-get install -y \
  libgtk-4-dev \
  libadwaita-1-dev \
  git \
  pkg-config \
  blueprint-compiler

# Install build dependencies
sudo dnf install -y \
  gtk4-devel \
  libadwaita-devel \
  git \
  pkg-config \
  blueprint-compiler

# Install build dependencies
sudo pacman -S \
  gtk4 \
  libadwaita \
  git \
  pkgconf \
  blueprint-compiler

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

macOS

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

Linux

# Set as default terminal emulator
sudo update-alternatives --install /usr/bin/x-terminal-emulator \
  x-terminal-emulator $(which ghostty) 50

# Configure default
sudo update-alternatives --config x-terminal-emulator

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

Ghostty won't start

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

Build fails with Zig errors

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.

Missing fonts after installation

Refresh font cache:

# Linux
fc-cache -fv

# List available fonts
ghostty +list-fonts

macOS: 'damaged' or 'unverified developer' error

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