Build Ghostty from Source

Tip

Building Ghostty from source is not recommended for most users. If you have access to a prebuilt binary or package, you should use that instead. See the binaries and packages page to see if a prebuilt binary or package is available for your platform.

To build Ghostty, you need Zig 0.13 installed.

Important

Zig 0.13 is required. Ghostty only guarantees that it can build against 0.13. Zig is still a fast-moving project so it is likely newer versions will not be able to build Ghostty yet. You can find binary releases of Zig release builds on the Zig downloads page.

The official build environment is defined by Nix. You do not need to use Nix to build Ghostty, but the Nix environment is the environment which runs CI tests and builds release artifacts, so it is the most reliable way to build Ghostty. See the Building with Nix section to see how to set up the Nix environment.

On Linux, you may need to install additional dependencies. See Linux Installation Tips. On macOS, you need Xcode installed with both the macOS and iOS SDKs enabled. See Mac .app.

With Zig and necessary dependencies installed, a binary can be built using zig build:

zig build -Doptimize=ReleaseFast

On Linux, this will build a ready-to-use binary at zig-out/bin/ghostty. On macOS, this will build the Xcode framework but additional steps are required to build the .app bundle. See Mac .app.

Tip

For a debug build, omit the -Doptimize=ReleaseFast flag. Debug builds are extremely slow (over 100x slower) than release builds, so only use them for development.

On Linux, you'll need to install header packages for Ghostty's dependencies before building it. Only a few dependencies are needed for source builds because Ghostty will build everything else statically by default.

Required dependencies:

• gtk4
• libadwaita
• pkg-config

On Ubuntu and Debian, use:

sudo apt install libgtk-4-dev libadwaita-1-dev git

On Arch Linux, use

sudo pacman -S gtk4 libadwaita

On Fedora variants, use

sudo dnf install gtk4-devel zig libadwaita-devel

On Fedora Atomic variants, use

rpm-ostree install gtk4-devel zig libadwaita-devel

Note

A recent GTK is required for Ghostty to work with Nvidia (GL) drivers under x11. Ubuntu 22.04 LTS has GTK 4.6 which is not new enough. Ubuntu 23.10 has GTK 4.12 and works. From this discussion the problem was fixed in GTK by Dec 2022. Also, if you are a BTRFS user, make sure to manually upgrade your Kernel (6.6.6 will work). The stock kernel in Ubuntu 23.10 is 6.5.0 which has a bug which causes zig to fail its hash check for packages.

Warning

GTK 4.14 on Wayland has a bug which may cause an immediate crash. There is an open issue to track this GTK bug. You can workaround this issue by running ghostty with GDK_DEBUG=gl-disable-gles ghostty.

If you are experiencing a segfault in cairo_scaled_font_get_font_options when running Ghostty, your Pango version may have a bug. See this discussion on GitHub for more information on how to resolve this.

Use zig build with the -p (prefix) flag to install Ghostty into a target directory. This will setup the proper FHS directory structure that ensures features such as shell integration, icons, GTK shortcuts, etc. all work.

For local, unprivileged installs, we recommend $HOME/.local:

zig build -p $HOME/.local -Doptimize=ReleaseFast
...

With a typical Freedesktop-compatible desktop environment (i.e. Gnome, KDE), this will make Ghostty available as an app in your app launcher. If you don't see it immediately you may have to log out and log back in or maybe even restart.

If Ghostty fails to launch using an app icon in your app launcher, ensure that ~/.local/bin is on your system PATH. The desktop environment itself must have that path in the PATH. Google for your specific desktop environment and distribution to learn how to do that.

The Nix build environment can be accessed like any other Nix dev shell, via the nix develop command (or nix-shell if you don't have the nix-command experimental feature enabled).

If you use nix-direnv, Ghostty provides an .envrc file you can source by running direnv allow. This will allow you to seamlessly enter and exit the Ghostty development environment as you enter and exit the Ghostty repository. Direnv is not required.

After setting up the Nix environment, you can run the same zig build as on other distributions or you can also build the package with Nix by running:

nix build .#ghostty

The binary would then be located under ./result/bin/ghostty.

Building with Nix should yield the same result as building it with Zig, but with higher reproducibility guarantees that ensure every part of Ghostty can be built reliably.

To build the macOS application, you must build on a macOS machine with Xcode installed and the active developer directory pointing to it. If you're not sure that's the case, check the output of xcode-select --print-path:

xcode-select --print-path
/Library/Developer/CommandLineTools        # <-- BAD

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcode-select --print-path
/Applications/Xcode.app/Contents/Developer # <-- GOOD

The above can happen if you install the Xcode Command Line Tools after Xcode is installed.

Next, make sure you have both the macOS and iOS SDKs installed (from inside Xcode → Settings → Platforms). Finally, build Ghostty and the app:

zig build -Doptimize=ReleaseFast
cd macos && xcodebuild

Note

If you're using the Nix environment on macOS, xcodebuild will fail due to the linker environment variables Nix sets. You must run the xcodebuild command specifically outside of the Nix environment.

This will output the app to macos/build/ReleaseLocal/Ghostty.app.

The "ReleaseLocal" build configuration is specifically for local release builds and disables some security features (such as "Library Validation") to make it easier to run without having to have a code signing identity and so on. These builds aren't meant for distribution. If you want a release build with all security features, use the official binary build.