# How to Build Ghostty from Source with Custom Build Options

> Build Ghostty from source with custom Zig build options. Learn how to use -D flags to select artifacts, target platforms, and toggle features for your build.

- Repository: [Ghostty/ghostty](https://github.com/ghostty-org/ghostty)
- Tags: how-to-guide
- Published: 2026-05-01

---

**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:

```bash
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`](https://github.com/ghostty-org/ghostty/blob/main/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:

```bash
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:

```bash
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`):

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

```

### Memory Testing on Linux

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

```bash
zig build run-valgrind

```

### Documentation Generation

Skip the executable and generate only Doxygen docs:

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

```

### Distribution Tarball

Create and verify a source distribution:

```bash
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`](https://github.com/ghostty-org/ghostty/blob/main/HACKING.md) in the repository root for the complete dependency list per distribution.