compiling ghostty on ubuntu 25.04+

Ghostty terminal emulator running on Ubuntu

comprehensive guide for building ghostty terminal from source on ubuntu 25.04 and newer distributions.

overview

ghostty is a fast, feature-rich terminal emulator written in zig. while the official build documentation provides basic instructions, ubuntu 25.04+ requires additional steps not covered in the official docs.

this guide addresses the gap left by outdated third-party repositories and incomplete official documentation.

critical missing dependencies

important: the official ghostty build documentation is missing two critical packages for ubuntu 25.04+:

libgtk4-layer-shell-dev
libgtk4-layer-shell0

without these packages, the build will fail with library not found errors. this guide includes all necessary dependencies.

why build from source

official ubuntu packages are not yet available
third-party ppa mkasberg/ghostty-ubuntu is outdated (v1.1.3 vs current v1.1.4)
control over build optimizations
access to latest features from main branch

prerequisites

system requirements

ubuntu 25.04 or newer
2gb+ ram for compilation
1gb+ disk space

checking ubuntu version

lsb_release -a
# should show Release: 25.04 or higher

installation steps

1. install build dependencies

install all required packages for building ghostty:

sudo apt update && sudo apt install -y \
  libgtk-4-dev \
  libadwaita-1-dev \
  git \
  blueprint-compiler \
  gettext \
  libxml2-utils \
  curl \
  xz-utils \
  libgtk4-layer-shell-dev \
  libgtk4-layer-shell0

breakdown of dependencies:

libgtk-4-dev: gtk4 development files
libadwaita-1-dev: gnome ui library
blueprint-compiler: ui blueprint compiler
libgtk4-layer-shell-dev: wayland layer shell support (missing from official docs)
libgtk4-layer-shell0: runtime library for wayland (missing from official docs)
xz-utils: needed to extract zig archive

2. download and install zig 0.14.1

ghostty requires zig 0.14.1 specifically:

# download zig
cd /tmp
curl -L https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz -o zig.tar.xz

# extract to /opt
sudo tar xf zig.tar.xz -C /opt
sudo mv /opt/zig-x86_64-linux-0.14.1 /opt/zig

# add to path (temporary)
export PATH=/opt/zig:$PATH

# verify installation
zig version
# should output: 0.14.1

3. clone ghostty repository

cd /opt
sudo git clone https://github.com/ghostty-org/ghostty
sudo chown -R $USER:$USER /opt/ghostty
cd ghostty

4. build ghostty

# build with release optimizations
/opt/zig/zig build -Doptimize=ReleaseFast

# verify build
./zig-out/bin/ghostty --version

expected output:

Ghostty 1.1.4-main+[commit-hash]

5. install ghostty system-wide

# copy binary
sudo cp zig-out/bin/ghostty /usr/local/bin/

# verify installation
ghostty --version

docker installation (alternative)

automated docker build

a pre-configured dockerfile is available for automated builds:

# download the dockerfile
curl -O https://michaelbommarito.com/wiki/ghostty-ubuntu-25.04.Dockerfile

# build ghostty in docker (takes ~3-5 minutes)
docker build -f ghostty-ubuntu-25.04.Dockerfile -t ghostty-build .

# extract built artifacts to your host
docker run --rm -v $(pwd)/ghostty-artifacts:/host-artifacts ghostty-build

# install ghostty from artifacts
cd ghostty-artifacts && sudo ./install.sh

# and you still need the gtk4-layer-shell-0 library at runtime
sudo apt install libgtk4-layer-shell0

# or install to custom location
# cd ghostty-artifacts && sudo ./install.sh /opt

the dockerfile:

builds ghostty with all optimizations
creates an installation script
packages everything for easy extraction
includes both binary and resources

artifacts produced

the docker build creates the following artifacts in ghostty-artifacts/:

ghostty-artifacts/
├── README.md                     # installation instructions
├── install.sh                    # automated installation script
└── ghostty/
    ├── VERSION.txt              # build version info
    ├── ghostty                  # the compiled binary
    └── share/                   # resources directory
        ├── applications/        # desktop entries
        ├── bash-completion/     # bash completions
        ├── fish/               # fish shell integration
        ├── ghostty/
        │   ├── shell-integration/  # shell integrations
        │   └── themes/         # 300+ color themes
        ├── icons/              # application icons
        ├── locale/             # translations (20+ languages)
        ├── metainfo/           # appstream metadata
        ├── nvim/               # neovim syntax files
        ├── terminfo/           # terminal capabilities
        ├── vim/                # vim syntax files
        └── zsh/                # zsh completions

total size: ~15mb uncompressed

manual docker build

for manual control, use an interactive container:

# start ubuntu 25.04 container
docker run -it ubuntu:25.04

# inside container, run all steps above
apt update && apt install -y \
  libgtk-4-dev libadwaita-1-dev git \
  blueprint-compiler gettext libxml2-utils \
  curl xz-utils libgtk4-layer-shell-dev \
  libgtk4-layer-shell0

# continue with zig download and build...

verification

verify successful build with detailed version info:

ghostty --version

should display:

version number (1.1.4 or newer)
build mode (ReleaseFast)
app runtime (gtk)
renderer (OpenGL)
gtk and libadwaita versions

configuration

ghostty configuration goes in ~/.config/ghostty/config. for a comprehensive configuration optimized for linux:

complete configuration guide - detailed setup with themes, keybindings, and performance tuning
download ready-to-use config - battle-tested configuration file

quick start:

mkdir -p ~/.config/ghostty
curl -o ~/.config/ghostty/config https://michaelbommarito.com/wiki/ghostty-config

troubleshooting

missing dependencies error

if build fails with missing libraries:

# check installed packages
dpkg -l | grep -E "gtk-4|adwaita"

# reinstall dependencies
sudo apt install --reinstall libgtk-4-dev libadwaita-1-dev

zig version mismatch

ghostty requires exactly zig 0.14.1:

# verify zig version
/opt/zig/zig version

# if wrong version, download correct one
curl -L https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz -o zig.tar.xz

gtk4 layer shell missing

this is the most common build error on ubuntu 25.04+ and is not documented in the official ghostty build guide:

error: unable to find dynamic system library 'gtk4-layer-shell-0' using strategy 'mode_first'. searched paths:
  /usr/lib/x86_64-linux-gnu/libgtk4-layer-shell-0.so
  /usr/local/lib/libgtk4-layer-shell-0.so
  /usr/lib/x86_64-linux-gnu/libgtk4-layer-shell-0.so
  /lib64/libgtk4-layer-shell-0.so
  /lib/libgtk4-layer-shell-0.so
  /usr/lib64/libgtk4-layer-shell-0.so
  /usr/lib/libgtk4-layer-shell-0.so
  /lib/x86_64-linux-gnu/libgtk4-layer-shell-0.so
  /usr/lib/x86_64-linux-gnu/libgtk4-layer-shell-0.a
  /usr/local/lib/libgtk4-layer-shell-0.a
  /usr/lib/x86_64-linux-gnu/libgtk4-layer-shell-0.a
  /lib64/libgtk4-layer-shell-0.a
  /lib/libgtk4-layer-shell-0.a
  /usr/lib64/libgtk4-layer-shell-0.a
  /usr/lib/libgtk4-layer-shell-0.a
  /lib/x86_64-linux-gnu/libgtk4-layer-shell-0.a

solution: install both the library and dev packages:

# must install both library and dev packages
sudo apt install libgtk4-layer-shell-dev libgtk4-layer-shell0

this dependency is required for wayland layer shell support on ubuntu 25.04+.

wayland vs x11 issues

ghostty supports both wayland and x11:

# force x11 if wayland issues
GDK_BACKEND=x11 ghostty

# check current session type
echo $XDG_SESSION_TYPE

build options

optimization levels

# debug build (faster compile, slower runtime)
zig build

# release build (recommended)
zig build -Doptimize=ReleaseFast

# smallest binary
zig build -Doptimize=ReleaseSmall

feature flags

# disable wayland support
zig build -Doptimize=ReleaseFast -Dwayland=false

# disable x11 support
zig build -Doptimize=ReleaseFast -Dx11=false

updating ghostty

to update to latest version:

cd /opt/ghostty
git pull
/opt/zig/zig build -Doptimize=ReleaseFast
sudo cp zig-out/bin/ghostty /usr/local/bin/

uninstalling

# remove binary
sudo rm /usr/local/bin/ghostty

# remove source (optional)
sudo rm -rf /opt/ghostty

# remove configuration (optional)
rm -rf ~/.config/ghostty

references

ghostty configuration guide - optimize your terminal setup
ghostty official documentation
ghostty github repository
zig downloads
gtk4 documentation