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.

If you intend to develop or package Ghostty, please also check out our "Developing Ghostty" and "Packaging Ghostty" documents respectively. This page is more oriented towards end users who want or need to build Ghostty from source for personal use.

To build Ghostty, you need to first install Zig.

Important

Each version of Ghostty is only guaranteed to build for one specific version of Zig as it is still a rapidly-evolving language. Either older or newer Zig compilers may not be able to build Ghostty. If your package manager maintains a different version of Zig than what Ghostty requires, you can use static binary releases of the Zig compiler on the Zig downloads page.

The Zig version that each Ghostty version requires is as follows:

Ghostty version	Zig version
1.0.x	0.13.0
1.1.x	0.13.0
1.2.x	0.14.1
tip	0.14.1

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.

Depending on your platform, you may also need to install additional dependencies to build Ghostty. For Linux, see Linux. For macOS, see macOS.

Begin by downloading Ghostty's source tarball.

Warning

While you can compile Ghostty from source by checking out its Git repository, this is not recommended for anyone but Ghostty developers and contributors. This is because source tarballs contain various preprocessed files that make Ghostty require far fewer dependencies to compile.

If you intend to contribute to Ghostty, please consult the "Developing Ghostty" documents on how to build Ghostty in a development environment. While most of the steps are exactly the same, we will be assuming a source tarball-based build for now on for the sake of simplicity.

For stable releases, source tarballs and their accompanying checksums can be found at releases.files.ghostty.org at the following paths, where VERSION is an unprefixed version number such as 1.0.0:

https://release.files.ghostty.org/VERSION/ghostty-VERSION.tar.gz
https://release.files.ghostty.org/VERSION/ghostty-VERSION.tar.gz.minisig

Signature files are signed with minisign using the following public key:

RWQlAjJC23149WL2sEpT/l0QKy7hMIFhYdQOFy0Z7z7PbneUgvlsnYcV

For development ("tip") versions, the source tarball can be found via the tip release on GitHub, under the name ghostty-source.tar.gz.

Important

The source tarball is different from GitHub's autogenerated tarball labelled "Source code (zip)" or "Source code (tar.gz)": the latter of which does not contain any preprocessed files, making it identical to a Git checkout.

Decompress the release tarball, and then navigate into the unpacked source folder:

tar -xf ghostty-VERSION.tar.gz
cd ghostty-VERSION/

# Or when using a tip source tarball:
# (REVISION is the commit SHA of the latest commit)

tar -xf ghostty-source.tar.gz
cd ghostty-VERSION-main+REVISION/

With Zig and necessary dependencies installed, a binary can then 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 app bundle at zig-out/Ghostty.app.

Tip

For Linux users: To install system-wide or on your user account, see Installation Directory.

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
• gtk4-layer-shell
• pkg-config or pkgconf
• gettext

Important

If you're using a Git checkout, you also need to install these dependencies:

Tip

If your distro has yet to package gtk4-layer-shell (e.g. Ubuntu 24.04, Debian 12, Linux Mint 22.1, OpenSUSE, etc.), you need to allow Ghostty to compile gtk4-layer-shell from source by adding the flag -fno-sys=gtk4-layer-shell to zig build.

doas apk add \
  gtk4.0-dev \
  libadwaita-dev \
  pkgconf \
  ncurses \
  gettext

sudo pacman -S \
  gtk4 \
  gtk4-layer-shell \
  libadwaita \
  gettext

sudo apt install \
  libgtk-4-dev \
  libgtk4-layer-shell-dev \
  libadwaita-1-dev \
  gettext \
  libxml2-utils

On Debian unstable/testing, the gcc-multilib package is also required for building.

On Fedora variants, use

sudo dnf install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  zig \
  libadwaita-devel \
  gettext

On Fedora Atomic variants, use

rpm-ostree install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  zig \
  libadwaita-devel \
  gettext

emerge -av \
  libadwaita \
  gtk \
  blueprint-compiler \
  gettext

sudo zypper install \
  gtk4-devel \
  libadwaita-devel \
  pkgconf \
  ncurses-devel \
  zig \
  gettext

sudo zypper install \
  gtk4-devel \
  libadwaita-devel \
  pkgconf \
  ncurses-devel \
  zig \
  gettext

sudo eopkg install \
  libgtk-4-devel \
  libadwaita-devel \
  pkgconf \
  zig \
  gettext

sudo xbps-install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  libadwaita-devel \
  pkg-config \
  zig \
  gettext

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.

For system-wide installs, we recommend /usr (likely requires sudo):

zig build -p /usr -Doptimize=ReleaseFast

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 → Components).

Ghostty also requires some additional library dependencies to be installed. You can choose to install them however you'd like, but the easiest way is via Homebrew:

brew install gettext

Note

If you're using the Nix development environment, these dependencies are handled for you and you do not need to install them manually.

zig build -Doptimize=ReleaseFast

This will output the app to zig-out/Ghostty.app.

The app created will use the "ReleaseLocal" Xcode build configuration. 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.