Building from Source

Learn how to build Ghostty from source code on macOS and Linux

This guide explains how to build Ghostty from source. Building from source is useful for contributing to development, testing new features, or creating custom builds.

Building from a Git checkout may require extra dependencies compared to building from a source tarball. Tip versions may also require different versions of Zig or other toolchains.

Prerequisites

All Platforms

• Zig - Ghostty requires a specific version of Zig (check build.zig.zon for the minimum version)
• Git - To clone the repository

Platform-Specific Requirements

macOS

Required:

• Xcode 26 and macOS 26 SDK
• iOS SDK
• Metal Toolchain

Main branch development requires Xcode 26 and the macOS 26 SDK. You do not need to be running macOS 26 to build Ghostty - you can use Xcode 26 on macOS 15 stable.

Ensure the correct version of Xcode is selected:

sudo xcode-select --switch /Applications/Xcode.app

Linux

Required:

• blueprint-compiler (version 0.16.0 or newer)
• GTK development libraries

Ubuntu/Debian:

sudo apt install blueprint-compiler libgtk-4-dev

Fedora:

sudo dnf install blueprint-compiler gtk4-devel

Arch Linux:

sudo pacman -S blueprint-compiler gtk4

Building Ghostty

1. Clone the repository

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

   Debug Build (Default)

   Build a debug version for development:

   zig build
   

   Debug builds include more logging and make diagnosing issues easier. This is the default and does not require any -Doptimize flags.

   Release Build

   Build an optimized release version:

   zig build -Doptimize=ReleaseFast
   
3. Run Ghostty

   zig build run
   

   You can pass additional arguments after --:

   zig build run -- --config-file=/path/to/config
   

Common Build Commands

Command	Description
zig build	Builds Ghostty (debug mode by default)
zig build run	Builds and runs Ghostty
zig build test	Runs unit tests
zig build test -Dtest-filter=<filter>	Runs tests matching the filter
zig build run-valgrind	Runs Ghostty under Valgrind (memory leak checking)
zig build update-translations	Updates translation strings
zig build dist	Builds a source tarball
zig build distcheck	Builds and validates a source tarball
zig build lib-vt	Builds libghostty-vt

Building libghostty-vt

Ghostty provides libghostty-vt, a C-compatible library for parsing terminal sequences:

zig build lib-vt

This library is available for Zig and C and compatible with macOS, Linux, Windows, and WebAssembly.

Development Tips

Running Tests

Run all tests:

zig build test

Run specific tests:

zig build test -Dtest-filter=terminal

Run libghostty-vt tests:

zig build test-lib-vt

Checking for Memory Leaks

On Linux, use Valgrind to check for memory leaks:

zig build run-valgrind

This builds Ghostty with Valgrind support and runs it with proper flags to suppress known false positives. You can pass the same arguments as zig build run.

Code Formatting

Zig code:

zig fmt .

Other files (Markdown, JSON, etc.):

prettier --write .

Make sure your Prettier version matches the version in nix/devShell.nix.

Nix files (if applicable):

alejandra .

Logging

Ghostty’s logging behavior depends on optimization level and environment variables:

• Debug builds output debug logs to stderr
• Release builds do not output debug logs to stderr

Control logging destinations with GHOSTTY_LOG:

# Enable all logging destinations
GHOSTTY_LOG=true zig build run

# Enable stderr only
GHOSTTY_LOG=stderr zig build run

# Enable macOS unified log (macOS only)
GHOSTTY_LOG=macos zig build run

# Disable specific destinations
GHOSTTY_LOG=no-stderr zig build run

View logs on macOS:

sudo log stream --level debug --predicate 'subsystem=="com.mitchellh.ghostty"'

View logs on Linux (systemd):

journalctl --user --unit app-com.mitchellh.ghostty.service

Nix Support

Ghostty provides Nix flake support for NixOS and Nix users:

Development Shell

nix develop

Build with Nix

nix build

Testing VMs

Run test VMs for different desktop environments:

nix run .#gnome-vm

Available VMs are defined in the nix/vm directory.

Troubleshooting Build Issues

Xcode version or SDK not found (macOS)

Ensure Xcode 26 is installed and selected:

xcode-select -p
sudo xcode-select --switch /Applications/Xcode.app

Verify the SDK is available:

xcrun --show-sdk-path

blueprint-compiler not found (Linux)

Install blueprint-compiler version 0.16.0 or newer:

# Ubuntu/Debian
sudo apt install blueprint-compiler

# Fedora
sudo dnf install blueprint-compiler

# Arch
sudo pacman -S blueprint-compiler

Zig version mismatch

Check the required Zig version in build.zig.zon and ensure your installed version meets the minimum requirement:

zig version

Download the correct version from ziglang.org.

Build fails with 'out of memory' error

Zig can be memory-intensive during compilation. Try:

1. Close other applications
2. Build with release optimizations: zig build -Doptimize=ReleaseFast
3. Increase system swap space

Next Steps

• Read the Contributing Guide to learn about the contribution process
• Check Troubleshooting for runtime issues
• See HACKING.md for detailed development information