How to Build Ghostty from Source with Custom Build Options

To build Ghostty from source, run zig build with -D flags to customize compile-time options like artifact selection, platform targets, and feature toggles defined in src/build/Config.zig.

Ghostty is a Zig-based terminal emulator that compiles through a unified zig build entry point in the ghostty-org/ghostty repository. The entire configuration system is exposed via command-line flags that control everything from executable output to SIMD acceleration and platform-specific packaging, allowing you to tailor the build without editing source files.

Understanding the Build System Architecture

The Entry Point (build.zig)

The top-level build.zig file serves as the build orchestration layer. When you invoke zig build, the script first reads standard options at lines 72‑76, then initializes the configuration struct. It handles feature-flag defaults through b.option calls (lines 70‑78, 84‑92, 124‑166) and wires build steps based on artifact selection booleans (lines 54‑62, 84‑106).

Configuration Parsing (Config.zig)

All -D flags are parsed by the Config struct declared in src/build/Config.zig. The Config.init function (lines 72‑124) builds a configuration instance by pulling values from command-line arguments, environment variables, and defaults. This centralizes control over whether to build the full GUI, library-only artifacts, or platform-specific bundles.

Essential Build Flags and Options

Ghostty exposes compile-time customization through boolean and string flags passed via -D<flag>=<value>.

Artifact Selection Flags

These flags control which outputs the build system produces:

• emit-exe: Build the Ghostty executable (default: true unless emit-lib-vt is set)
• emit-lib-vt: Build only the libghostty-vt static library without GUI components (default: false)
• emit-macos-app: Generate a macOS .app bundle (default: !emit-lib-vt && emit-xcframework)
• emit-xcframework: Build an XCFramework for macOS library distribution requiring xcodebuild (default: false on non-macOS, auto-detect on macOS)
• emit-docs: Generate Doxygen documentation requiring pandoc (default: false unless detected)
• emit-bench: Include benchmark binaries (default: false)

Platform and Packaging Flags

• flatpak / snap: Enable platform-specific packaging hooks (default: false)
• sentry: Link Sentry crash-reporting framework (default: true on macOS, false elsewhere)
• i18n: Enable gettext-based localization (default: true on macOS/Unix with glibc)

Optimization and Linking Flags

• simd: Enable SIMD-accelerated code paths (default: true, disabled on Wasm)
• pie: Build position-independent executable (default: true for system packages)
• strip: Strip symbols from final binary (default: false in Debug, true in ReleaseFast/ReleaseSmall)

Platform-Specific Build Instructions

macOS Requirements

The build system defaults to a generic macOS target to work around a known compiler issue (see genericMacOSTarget in Config.zig). Building the full GUI requires Xcode 26 and the macOS 26 SDK. To produce a standalone macOS app bundle without the XCFramework:

zig build -Demit-xcframework=false -Demit-macos-app=true

Linux (GTK) Configuration

The GTK rendering backend in src/termio/backend.zig automatically detects X11 and Wayland support. Explicitly control display server linking with:

• Enable Wayland only: zig build -Dgtk-wayland=true -Dgtk-x11=false
• Enable X11 only: zig build -Dgtk-x11=true -Dgtk-wayland=false

Lines 212‑219 of build.zig handle this platform-specific logic. Additional dependencies like blueprint-compiler are documented in HACKING.md.

WebAssembly Targets

For Wasm builds, the wasm_target is fixed to .browser and the emit-wasm flow requires the wasm_shared flag. SIMD is automatically disabled on this target.

Practical Build Recipes

Standard Debug Build

Clone the repository and build with default settings:

git clone https://github.com/ghostty-org/ghostty
cd ghostty
zig build
./zig-out/bin/ghostty

Library-Only Release Build

Generate an optimized static library without the executable or crash reporting:

zig build -Doptimize=ReleaseFast \
          -Demit-lib-vt=true \
          -Demit-exe=false \
          -Dsimd=true \
          -Dsentry=false

Running with Custom Resources

The run step automatically injects GHOSTTY_RESOURCES_DIR (lines 245‑257 of build.zig):

zig build run -- -c /my/custom/config

Memory Testing on Linux

Wrap the executable with Valgrind using the built-in target (lines 96‑115):

zig build run-valgrind

Documentation Generation

Skip the executable and generate only Doxygen docs:

zig build -Demit-docs=true -Demit-exe=false

Distribution Tarball

Create and verify a source distribution:

zig build dist        # Creates ghostty-<version>.tar.gz in zig-out

zig build distcheck   # Extracts, builds, and runs sanity checks

Summary

• Ghostty uses a unified Zig build system controlled entirely through -D flags in src/build/Config.zig
• Artifact selection (emit-exe, emit-lib-vt, emit-macos-app) determines whether you build the GUI, library, or macOS bundle
• Platform flags (flatpak, snap, sentry, i18n) handle packaging and OS-specific features
• Performance flags (simd, pie, strip) control optimization and binary characteristics
• The build system auto-configures GTK backends for Linux and generic macOS targets to avoid compiler issues

Frequently Asked Questions

What flags do I need to build only the Ghostty library without the GUI?

Pass -Demit-lib-vt=true -Demit-exe=false to produce only the libghostty-vt static library. This skips the GUI components and any macOS-specific bundling logic, as implemented in the artifact selection logic at lines 54‑62 of build.zig.

How do I create a macOS app bundle without the XCFramework?

By default, macOS builds may produce an XCFramework. To build a standalone .app bundle without the XCFramework, explicitly disable it: zig build -Demit-xcframework=false -Demit-macos-app=true. This follows the boolean logic defined in Config.zig where emit-macos-app defaults to the presence of emit-xcframework when not explicitly set.

Can I build Ghostty with debugging symbols for development?

Yes. Use -Doptimize=Debug (the default) and ensure -Dstrip=false to retain symbols. The strip flag defaults to false in Debug builds but true in ReleaseFast/ReleaseSmall modes, as parsed by the configuration struct in src/build/Config.zig.

What dependencies are required for building on Linux?

Linux builds require the GTK development libraries and blueprint-compiler. The build system auto-detects X11 and Wayland support (lines 212‑219 of build.zig), but you must install system dependencies manually. Refer to HACKING.md in the repository root for the complete dependency list per distribution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}