compiling ghostty on ubuntu 25.10

published: September 22, 2025 •
ghosttyterminalubuntu25.10buildcompilationziggtk4docker
on this page
Ghostty terminal showing Ubuntu 25.10 Questing Quokka release information

comprehensive guide for building ghostty terminal from source on ubuntu 25.10.

overview

ghostty is a fast, feature-rich terminal emulator written in zig. while the official build documentation covers basics, ubuntu 25.10 requires additional packages and steps for successful compilation.

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

note: for ubuntu 25.04 users, see the ubuntu 25.04 ghostty build guide.

additional ubuntu 25.10 dependencies

important: beyond the official docs, ubuntu 25.10 requires:

  • libgtk4-layer-shell0 - runtime library (dev package alone is insufficient)
  • blueprint-compiler - required for ui compilation
  • build-essential - standard build tools
  • pkg-config - library discovery during build

without these packages, the build will fail. this guide includes all necessary dependencies.

why build from source

  • official ubuntu packages are not yet available
  • third-party ppas are outdated or missing
  • control over build optimizations
  • access to latest features from main branch

prerequisites

system requirements

  • ubuntu 25.10
  • 2gb+ ram for compilation
  • 1gb+ disk space

checking ubuntu version

lsb_release -a
# should show Release: 25.10

installation steps

prerequisites

# install docker if needed
sudo apt update && sudo apt install -y docker.io

runtime dependencies

if running the docker-built binary on your host system, install runtime dependencies:

# Install runtime dependencies for Ghostty
sudo apt update && sudo apt install -y \
    libgtk-4-1 \
    libadwaita-1-0 \
    libgtk4-layer-shell0

build with docker

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

# build ghostty in docker (takes ~3-5 minutes)
docker build \
  -f ghostty-ubuntu-25.10.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/scripts && 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

docker build options

# build specific version
docker build --build-arg GHOSTTY_VERSION=v1.2.0 -f ghostty-ubuntu-25.10.Dockerfile -t ghostty-build .

manual build method

step 1: install build dependencies

# Update package lists
sudo apt update

# Install all required dependencies
sudo apt install -y \
  build-essential \
  libgtk-4-dev \
  libadwaita-1-dev \
  git \
  blueprint-compiler \
  gettext \
  libxml2-utils \
  curl \
  xz-utils \
  pkg-config \
  libgtk4-layer-shell-dev \
  libgtk4-layer-shell0 \
  ca-certificates

# Verify GTK4 installation
pkg-config --modversion gtk4

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
  • libgtk4-layer-shell0: runtime library (often overlooked)
  • pkg-config: finds libraries during build

step 2: download and install zig 0.14.1

ghostty requires zig 0.14.1 specifically:

# Create directory for Zig
sudo mkdir -p /opt/zig

# Download Zig 0.14.1
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 and install
sudo tar xf zig.tar.xz -C /opt
sudo mv /opt/zig-x86_64-linux-0.14.1/* /opt/zig/
sudo rmdir /opt/zig-x86_64-linux-0.14.1

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

# Make permanent (add to ~/.bashrc)
echo 'export PATH=/opt/zig:$PATH' >> ~/.bashrc
source ~/.bashrc

# Verify installation
zig version
# Output: 0.14.1

step 3: clone and build ghostty

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

# Optional: checkout specific version
# git checkout v1.2.0

# Build with optimizations
zig build -Doptimize=ReleaseFast

# Run tests (optional but recommended)
zig build test

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

step 4: install system-wide

# Install binary
sudo cp zig-out/bin/ghostty /usr/local/bin/
sudo chmod +x /usr/local/bin/ghostty

# Install resources (themes, completions, etc.)
sudo cp -r zig-out/share/* /usr/local/share/

# Update desktop database
sudo update-desktop-database /usr/local/share/applications

# Verify installation
which ghostty
ghostty --version

automated script installation

for quick automated installation:

# download automated build script
curl -O https://michaelbommarito.com/wiki/ghostty-ubuntu-25.10-install.sh
chmod +x ghostty-ubuntu-25.10-install.sh
./ghostty-ubuntu-25.10-install.sh

build options

optimization levels

# Debug build (fast compile, slower runtime, debug symbols)
zig build

# Release build (balanced optimization)
zig build -Doptimize=ReleaseSafe

# Maximum performance (recommended for daily use)
zig build -Doptimize=ReleaseFast

# Smallest binary size
zig build -Doptimize=ReleaseSmall

feature flags

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

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

cross-compilation

configuration

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

quick start:

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

verification

verify successful build with:

ghostty --version

should display:

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

troubleshooting

missing gtk4 layer shell

if build fails with missing gtk4-layer-shell-0:

sudo apt install libgtk4-layer-shell-dev libgtk4-layer-shell0

zig version mismatch

ghostty requires exactly zig 0.14.1:

# Remove old Zig
sudo rm -rf /opt/zig

# Install correct version
curl -L https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz -o zig.tar.xz
sudo tar xf zig.tar.xz -C /opt
sudo mv /opt/zig-x86_64-linux-0.14.1 /opt/zig

wayland vs x11 issues

ghostty supports both wayland and x11:

# Check session type
echo $XDG_SESSION_TYPE

# Force X11 backend
export GDK_BACKEND=x11
ghostty

updating ghostty

to update to latest version:

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

uninstalling

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

# Remove resources
sudo rm -rf /usr/local/share/ghostty
sudo rm -rf /usr/local/share/applications/*ghostty*
sudo rm -rf /usr/local/share/icons/hicolor/**/apps/*ghostty*

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

references

related pages

more in programming

on this page