Documentation · BlinkGTK

BlinkGTK Installation Guide

Instructions for installing the binary distribution of BlinkGTK. Like
WebKitGTK, BlinkGTK ships split packages: runtime (required to run apps) and
devel (required to build apps that embed BlinkGTK). Fetch the binaries
(RPM / DEB / tarball) from GitHub Releases. Building from source is not part of
the distribution (binary-only).

Contents

  1. System Requirements
  2. Package Layout (runtime / devel)
  3. Installation
  4. Verifying the Installation
  5. Building a Consumer App
  6. Uninstall
  7. Troubleshooting

System Requirements

Item Requirement
CPU x86_64 (64-bit)
Memory 2GB minimum, 4GB+ recommended
Disk ~700MB for the runtime
OS Linux (Fedora 44+, Ubuntu 24.04+, Debian 13+)
Display Wayland only (no X11)
GTK4 >= 4.6.0
GLib >= 2.70.0

Runtime dependencies (shared libraries needed to run apps):

# Fedora / RHEL
sudo dnf install gtk4 glib2 wayland vulkan-loader
# Debian / Ubuntu
sudo apt install libgtk-4-1 libglib2.0-0 libwayland-client0 libvulkan1

The full Chromium runtime (500+ .so for V8 / Blink / Viz, plus resources) is
bundled in the runtime package's private directory
(/usr/lib64/blinkgtk-0.1/), so no separate installation is required.

Package Layout (runtime / devel)

Package Purpose Main contents

|

blinkgtk-bin (runtime) | run apps | /usr/lib64/libblinkgtk-0.1.so.0 (public ABI) + /usr/lib64/blinkgtk-0.1/ (Chromium, private) + /usr/libexec/blinkgtk-0.1/ (simple_browser) + THIRD_PARTY_NOTICES.html |
|

blinkgtk-bin-devel (devel) | build consumers | headers (/usr/include/blinkgtk-0.1/) + pkg-config (/usr/lib64/pkgconfig/blinkgtk-0.1.pc) + .so symlink |
|

blinkgtk-bin-gir (gir) | introspection (Python/Rust/…) | BlinkGTK-0.1.typelib | Install runtime only to run apps; add devel (+ gir) to develop apps that
embed BlinkGTK.

Installation

Fetch the release assets from GitHub Releases (verify with SHA256SUMS).

Fedora / RHEL (RPM)

# runtime only (run apps)
sudo dnf install ./blinkgtk-bin-<VERSION>-1.fc44.x86_64.rpm

# for development, add devel + gir
sudo dnf install ./blinkgtk-bin-devel-<VERSION>-1.fc44.x86_64.rpm \
                 ./blinkgtk-bin-gir-<VERSION>-1.fc44.x86_64.rpm

Debian / Ubuntu (DEB)

sudo apt install ./libblinkgtk-0.1-0_<VERSION>_amd64.deb        # runtime
sudo apt install ./libblinkgtk-0.1-dev_<VERSION>_amd64.deb      # devel

Tarball (FHS layout)

Both runtime and devel use an FHS layout (usr/lib64/...). Extract at root (/).

# runtime
sudo tar xzf blinkgtk-<VERSION>-linux-x86_64.tar.gz -C /
sudo ldconfig                                    # apply ld.so.conf.d

# devel (only when developing consumers)
sudo tar xzf blinkgtk-devel-<VERSION>-linux-x86_64.tar.gz -C /

ldconfig applies /etc/ld.so.conf.d/blinkgtk-0.1.conf (bundled in runtime),
which adds the private directory to the loader search path.

Verifying the Installation

runtime

$ ldconfig -p | grep libblinkgtk-0.1
    libblinkgtk-0.1.so.0 (libc6,x86-64) => /usr/lib64/libblinkgtk-0.1.so.0

# demo browser (in a Wayland session)
$ /usr/libexec/blinkgtk-0.1/simple_browser

devel (pkg-config)

$ pkg-config --modversion blinkgtk-0.1
<VERSION>

$ pkg-config --libs blinkgtk-0.1
-L/usr/lib64 -L/usr/lib64/blinkgtk-0.1 -L/usr/lib64/blinkgtk-0.1/chromium \
  -lblinkgtk-0.1 -lbase_allocator_partition_allocator_src_partition_alloc_allocator_shim ...

Important: --libs includes the PartitionAlloc allocator shim. Consumers
must link via pkg-config — if the shim is not linked directly into the
executable, Chromium navigation fails (Issue #90).

gir (Python / PyGObject)

$ python3 -c "import gi; gi.require_version('BlinkGTK','0.1'); from gi.repository import BlinkGTK; print('BlinkGTK OK')"
BlinkGTK OK

Building a Consumer App

Build apps that embed BlinkGTK with pkg-config (the direct shim link is added
automatically):

cc my_app.c -o my_app $(pkg-config --cflags --libs blinkgtk-0.1)

See the consumer integration guide
(lifecycle / embedding a WebView / GPU mode / injection, etc.).

Uninstall

RPM

sudo dnf remove blinkgtk-bin blinkgtk-bin-devel blinkgtk-bin-gir

DEB

sudo apt remove libblinkgtk-0.1-0 libblinkgtk-0.1-dev

Tarball

The tarball places files under FHS paths, so remove them manually (RPM/DEB with
package management is preferred). Main locations: /usr/lib64/libblinkgtk-0.1.so*,
/usr/lib64/blinkgtk-0.1/, /usr/libexec/blinkgtk-0.1/,
/etc/ld.so.conf.d/blinkgtk-0.1.conf, /usr/include/blinkgtk-0.1/ (devel),
/usr/lib64/pkgconfig/blinkgtk-0.1.pc (devel). Run sudo ldconfig afterwards.

Troubleshooting

1. libblinkgtk-0.1.so.0: cannot open shared object file

The private directory is not in the loader search path.

sudo ldconfig                          # apply /etc/ld.so.conf.d/blinkgtk-0.1.conf
ldconfig -p | grep libblinkgtk-0.1     # confirm resolution

2. pkg-config does not find blinkgtk-0.1

The devel package is not installed, or PKG_CONFIG_PATH is unset.

export PKG_CONFIG_PATH=/usr/lib64/pkgconfig:$PKG_CONFIG_PATH
pkg-config --modversion blinkgtk-0.1

3. Black screen / navigation fails in your app (Issue #90)

The consumer is not linking the allocator shim directly. Link via pkg-config
(pkg-config --libs blinkgtk-0.1 includes the shim). Verify:
readelf -d ./my_app | grep NEEDED | grep partition_alloc_allocator_shim returns
one entry.

4. Python import error (Namespace BlinkGTK not available)

The gir package is not installed, or GI_TYPELIB_PATH is unset.

export GI_TYPELIB_PATH=/usr/lib64/girepository-1.0:$GI_TYPELIB_PATH

5. Failed to open Wayland display

BlinkGTK supports Wayland only (no X11).

echo $WAYLAND_DISPLAY    # if empty, re-login into a Wayland session

Next Steps

  1. Consumer integration guide: consumer-integration-guide-en.md
  2. C tutorial: building-with-blinkgtk-en.md
  3. Python / Rust: python-tutorial-en.md

Support

Copyright 2026 BlinkGTK Project
SPDX-License-Identifier: BSD-3-Clause