从源码构建 Ghostty

自行从源码构建 Ghostty。仅推荐给无法获得二进制或软件包的人， 以及想为 Ghostty 做贡献的开发者。

Tip

不建议大多数用户从源码构建 Ghostty。 如果你可以获得预构建的二进制或软件包，应当改用后者。请查看二进制与软件包页面，看你的平台是否有预构建的二进制或软件包。

如果你打算开发或打包 Ghostty，也请分别查看我们的"开发 Ghostty"与"打包 Ghostty"文档。本页更面向为了个人使用而想要或必须从源码构建 Ghostty 的最终用户。

要构建 Ghostty，你需要先安装 Zig。

Important

由于 Zig 仍是一门快速演化的语言，每个 Ghostty 版本只保证能用一个特定版本的 Zig 构建。更旧或更新的 Zig 编译器都可能无法构建 Ghostty。 如果你的包管理器维护的 Zig 版本与 Ghostty 所要求的不同，可以使用 Zig 下载页上的静态二进制发行版的 Zig 编译器。

每个 Ghostty 版本所需的 Zig 版本如下：

Ghostty 版本Zig 版本
1.0.x0.13.0
1.1.x0.13.0
1.2.x0.14.1
1.3.x0.15.2
tip0.15.2

官方构建环境由 Nix定义。构建 Ghostty 不需要使用 Nix，但 Nix 环境是运行 CI 测试与构建发行工件的环境，因此它是构建 Ghostty 最可靠的方式。如何设置 Nix 环境见用 Nix 构建一节。

依平台不同，你还可能需要安装其他依赖来构建 Ghostty。Linux 见 Linux，macOS 见 macOS。

获取源码

首先下载 Ghostty 的源码 tarball。

Warning

虽然你可以通过检出 Git 仓库从源码编译 Ghostty，但这不推荐给除 Ghostty 开发者与贡献者之外的任何人。这是因为源码 tarball 包含各种预处理的文件，使 Ghostty 编译所需的依赖少得多。

如果你打算为 Ghostty 做贡献，请查阅"开发 Ghostty"文档了解如何在开发环境中构建 Ghostty。虽然多数步骤完全相同，但为简单起见，从这里开始我们都假定基于源码 tarball 的构建。

对稳定发行版而言，源码 tarball 及其随附的校验和可在 release.files.ghostty.org 通过以下路径找到，其中 VERSION 是不带前缀的版本号，如 1.0.0：

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

签名文件由 minisign用以下公钥签署：

RWQlAjJC23149WL2sEpT/l0QKy7hMIFhYdQOFy0Z7z7PbneUgvlsnYcV

对开发（"tip"）版本而言，源码 tarball 可通过 GitHub 上的 tip release获取，名为 ghostty-source.tar.gz。

Important

源码 tarball 与 GitHub 自动生成的标为 "Source code (zip)" 或 "Source code (tar.gz)" 的 tarball 不同：后者不含任何预处理文件，与 Git 检出无差别。

解压发行 tarball，然后进入解包后的源码文件夹：

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/

安装好 Zig 与必要依赖后，即可用 zig build 构建二进制：

zig build -Doptimize=ReleaseFast

在 Linux 上，这会在 zig-out/bin/ghostty生成就绪可用的二进制。在 macOS 上，这会在 zig-out/Ghostty.app生成 app bundle。

Tip

对 Linux 用户：要安装到系统级或你的用户账户，见安装目录。

Tip

要构建调试版本，省略 -Doptimize=ReleaseFast 旗标。调试构建极慢（比 release 构建慢 100 倍以上），所以只用于开发。

Linux

依赖

在 Linux 上，构建 Ghostty 之前需要安装 Ghostty 依赖的头文件包。源码构建只需要少量依赖，因为 Ghostty 默认把其余一切都静态构建。

必需依赖：

  • gtk4
  • libadwaita
  • gtk4-layer-shell
  • pkg-config 或 pkgconf
  • gettext

Important

如果用的是 Git 检出，还需安装这些依赖：

Tip

如果你的发行版尚未打包 gtk4-layer-shell（如 Ubuntu 24.04、Debian 12、Linux Mint 22.1、OpenSUSE 等），你需要允许 Ghostty 从源码编译 gtk4-layer-shell，方法是向 zig build添加旗标 -fno-sys=gtk4-layer-shell。

Alpine 

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

Arch Linux 

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

Debian 与 Ubuntu 

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

在 Debian unstable/testing 上，构建时还需要 gcc-multilib 软件包。

Fedora

在 Fedora 变体上，使用

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

在 Fedora Atomic 变体上，使用

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

Gentoo 

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

openSUSE Tumbleweed 

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

openSUSE Leap 

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

Solus 

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

Void 

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

安装目录

用 -p（prefix）旗标配合 zig build，把 Ghostty 安装到目标目录。这会设置正确的 FHS 目录结构，确保 shell 集成、图标、GTK 快捷键等功能都正常工作。

对本地、无特权的安装，我们推荐 $HOME/.local：

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

在典型的 Freedesktop 兼容桌面环境（如 GNOME、KDE）下，这会让 Ghostty 作为应用出现在你的应用启动器里。如果没有立刻看到，可能需要注销再登录，甚至重启。

如果 Ghostty 通过应用启动器中的应用图标启动失败，请确保 ~/.local/bin 位于你 系统 的 PATH上。桌面环境本身必须在 PATH中包含该路径。针对你的具体桌面环境与发行版搜索一下吧。

如果你用 -fno-sys=gtk4-layer-shell 旗标构建了 Ghostty，可能还需要把 LD_LIBRARY_PATH 环境变量设为 $HOME/.local/lib。为避免从桌面环境启动时污染全局的 LD_LIBRARY_PATH，可以直接用 patchelf给已安装的 Ghostty elf 打补丁：

patchelf --set-rpath '$ORIGIN/../lib' $HOME/.local/bin/ghostty

对系统级安装，我们推荐 /usr（很可能需要 sudo）：

zig build -p /usr -Doptimize=ReleaseFast

用 Nix 构建

Nix 构建环境可以像任何其他 Nix dev shell那样，通过 nix develop 命令进入（若未启用 nix-command 实验特性，则用 nix-shell）。

如果你使用 nix-direnv，Ghostty 提供了一个 .envrc 文件，运行 direnv allow即可 source 它。这让你进入和离开 Ghostty 仓库时无缝地进入和离开 Ghostty 开发环境。Direnv 非必需。

设置好 Nix 环境后，可以运行与其他发行版相同的 zig build，或者也可以用 Nix 构建软件包：

nix build .#ghostty

之后二进制位于 ./result/bin/ghostty下。

用 Nix 构建应得到与用 Zig 构建相同的结果，但具有更高的可复现性保证，确保 Ghostty 的每个部件都能可靠构建。

macOS

依赖

Xcode

要构建 macOS 应用，必须在装有 Xcode、且活动开发者目录指向它的 macOS 机器上构建。如果你不能确定是否如此，检查 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

如果在安装 Xcode 之后 才安装 Xcode Command Line Tools，可能发生上述情况。

接下来，确保已安装 macOS SDK、iOS SDK 与 Metal Toolchain（在 Xcode → Settings → Components 内）。

其他依赖

Ghostty 还需要安装一些额外的库依赖。安装方式随意，但最简单的是通过 Homebrew：

brew install gettext

Note

如果你使用 Nix 开发环境，这些依赖会自动处理，无需手动安装。

Mac .app 

zig build -Doptimize=ReleaseFast

这会把应用输出到 zig-out/Ghostty.app。

创建的应用使用 "ReleaseLocal" Xcode 构建配置。该配置专用于本地 release 构建，并禁用一些安全特性（如 "Library Validation"），以便更容易在没有代码签名身份等情况下运行。这些构建不用于分发。如果你想要带全部安全特性的 release 构建，使用官方二进制构建。


Edit on GitHub