Skip to main content
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

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

​
Building Ghostty

1

Clone the repository

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

Build the project

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.
3

Run Ghostty

zig build run
You can pass additional arguments after --:
zig build run -- --config-file=/path/to/config

​
Common Build Commands

CommandDescription
zig buildBuilds Ghostty (debug mode by default)
zig build runBuilds and runs Ghostty
zig build testRuns unit tests
zig build test -Dtest-filter=<filter>Runs tests matching the filter
zig build run-valgrindRuns Ghostty under Valgrind (memory leak checking)
zig build update-translationsUpdates translation strings
zig build distBuilds a source tarball
zig build distcheckBuilds and validates a source tarball
zig build lib-vtBuilds 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

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
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
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.
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