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 (glibc 2.43 or later; Fedora 44+, Ubuntu 25.10+)
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 (dnf repository — let dnf handle updates)

Register the repository once and dnf upgrade will pick up new releases.
No need to download files each time.

sudo curl -o /etc/yum.repos.d/blinkgtk.repo \
  https://blinkgtk.org/repo/fedora/blinkgtk.repo

sudo dnf install blinkgtk-bin                          # runtime
sudo dnf install blinkgtk-bin-devel blinkgtk-bin-gir   # for development

Packages are signed and the .repo ships with gpgcheck=1. The first
dnf install asks you to confirm the public key — check that the
fingerprint matches:

D3A0 3E93 E845 4347 D52D  4372 2F48 F4B7 5395 96DA

This key expires on 2028-07-06. Once it does, dnf can no longer verify
signatures and updates stop. We will publish a new key before then and replace
the fingerprint on this page. After that, import the new key like this:

sudo rpm --import https://blinkgtk.org/repo/fedora/RPM-GPG-KEY-blinkgtk

Check the fingerprint on this page before importing. The key is served from
the same place as the packages, so comparing the fingerprint is the only way to
establish that the key itself is the right one. You can also read the
fingerprint of the key currently served:

curl -s https://blinkgtk.org/repo/fedora/RPM-GPG-KEY-blinkgtk \
  | gpg --show-keys --with-fingerprint

Repository metadata is hosted on blinkgtk.org while the packages themselves
live in GitHub Releases. dnf follows the metadata to fetch them, so there
is nothing for you to switch between.

Fedora / RHEL (individual RPMs)

If you prefer not to register the repository, install downloaded RPMs
directly.

# 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