Migrating from WebKitGTK

Author: BlinkGTK Project
Last updated: 2026-07-30

日本語

A guide for moving a WebKitGTK 6.0 (GTK4) application to BlinkGTK. The shortest
migration path comes first, followed by a mechanical replacement checklist, the
API mapping tables, the design differences, and an honest list of what WebKitGTK
has that BlinkGTK does not. Every BlinkGTK API named here is mechanically
verified to exist in the bundled header and shared library.

Get it running first

Migrating a typical WebKitGTK app changes only a handful of lines of code. In
addition there are two BlinkGTK-specific preparations that WebKitGTK does
not have:

1. Linking must go through pkg-config — pkg-config --cflags --libs blinkgtk-0.1.
   Hand-written link lines miss required libraries and the app crashes right
   after startup
2. Chromium runtime resources must be in place — files such as icudtl.dat
   and locales/ are needed at run time. Use the bundled run-with-resources
   wrapper, or point at them with blink_gtk_set_resources_path()

Both are covered step by step in
Building your application.

Before — WebKitGTK 6.0

#include <webkit/webkit.h>
#include <gtk/gtk.h>

int main(int argc, char *argv[])
{
    gtk_init();

    GtkWidget *window = gtk_window_new();
    gtk_window_set_title(GTK_WINDOW(window), "WebKitGTK Browser");
    gtk_window_set_default_size(GTK_WINDOW(window), 1024, 768);

    WebKitWebView *web_view = WEBKIT_WEB_VIEW(webkit_web_view_new());
    gtk_window_set_child(GTK_WINDOW(window), GTK_WIDGET(web_view));

    webkit_web_view_load_uri(web_view, "https://example.com/");
    gtk_window_present(GTK_WINDOW(window));

    GMainLoop *loop = g_main_loop_new(NULL, FALSE);
    g_main_loop_run(loop);
    return 0;
}

After — BlinkGTK

#include <blink_gtk/blink_gtk.h>
#include <gtk/gtk.h>

int main(int argc, char *argv[])
{
    /* Change 1: initialize the engine before GTK */
    if (!blink_gtk_init(&argc, &argv)) {
        g_printerr("blink_gtk_init() failed\n");
        return 1;
    }
    gtk_init();

    GtkWidget *window = gtk_window_new();
    gtk_window_set_title(GTK_WINDOW(window), "BlinkGTK Browser");
    gtk_window_set_default_size(GTK_WINDOW(window), 1024, 768);

    /* Change 2: create the WebView. It returns GtkWidget*, so no cast is
     * needed to make it a child */
    GtkWidget *web_view = blink_web_view_new();
    gtk_window_set_child(GTK_WINDOW(window), web_view);

    /* Change 3: cast with BLINK_WEB_VIEW() when calling BlinkGTK APIs */
    blink_web_view_load_uri(BLINK_WEB_VIEW(web_view), "https://example.com/");
    gtk_window_present(GTK_WINDOW(window));

    /* Change 4: use the BlinkGTK main loop */
    int status = blink_gtk_run_main_loop();

    /* Change 5: shut down */
    blink_gtk_shutdown();
    return status;
}

Build command change

# Before
cc app.c -o app $(pkg-config --cflags --libs gtk4 webkitgtk-6.0)

# After
cc app.c -o app $(pkg-config --cflags --libs blinkgtk-0.1)

Mechanical replacements (checklist)

• #include <webkit/webkit.h> → #include <blink_gtk/blink_gtk.h>
• Add blink_gtk_init(&argc, &argv) before gtk_init()
• Switch the main loop to blink_gtk_run_main_loop() / blink_gtk_quit_main_loop()
• Add blink_gtk_shutdown() on exit
• webkit_web_view_new() → blink_web_view_new() (returns GtkWidget*)
• WEBKIT_WEB_VIEW(x) → BLINK_WEB_VIEW(x)
• webkit_web_view_load_uri() → blink_web_view_load_uri()
• Remove webkit_web_view_get_settings() calls (settings go directly on the WebView; see below)
• pkg-config package name: webkitgtk-6.0 → blinkgtk-0.1
• Put the runtime resources in place (see Building your application)

API mapping

Settings (WebKitSettings equivalent)

BlinkGTK has no Settings object. Settings are applied directly to the WebView.

Each set_* has a matching get_*. Details:
Settings API

Navigation

Details: Navigation API

Signals

Details: Signals API

Talking to the page

Details: App integration API

Customizing the UI

Details: UI handlers API

Everything else

To find a function by goal, see How do I…?.

Where the thinking changes

1. No Settings / Manager / Controller objects — WebKitGTK hands you helper
   objects via webkit_web_view_get_settings() and friends; BlinkGTK puts every
   API directly on the WebView
2. The type is GtkWidget* — blink_web_view_new() returns GtkWidget*.
   Pass it to GTK as is; cast with BLINK_WEB_VIEW() for BlinkGTK APIs
3. Strict initialization order — call blink_gtk_init() before GTK
   (see the lifecycle figure)
4. Runtime resources must be deployed — Chromium data files are required at
   run time. WebKitGTK has no such step, so check this first when migrating
5. A Wayland session is required — BlinkGTK is Wayland-only and does not run
   in X11-only environments (WebKitGTK does, so this is a real difference)
6. The developer tools are Chrome DevTools — instead of WebInspector you get
   Chrome DevTools, including remote debugging
   (DevTools API)

What WebKitGTK has that BlinkGTK does not (yet)

Being honest here. The following currently have no equivalent:

• WebExtensions (in-WebProcess extension mechanism)
• Direct control equivalent to WebKitWebContext / WebKitNetworkSession —
  proxy settings, cache control, custom data directories
• A print dialog — only PDF output via blink_web_view_print_to_pdf()
• Editing commands (webkit_web_view_execute_editing_command() equivalent)

If any of these block your migration, please tell us at
bug reports & requests or
contact@blinkgtk.org.

Frequently asked questions

Can I use WebKitGTK and BlinkGTK in the same process?

Not recommended. Both carry large runtimes; memory usage grows and unexpected
interference (symbols, main-loop contention) is possible.

How is the performance?

JavaScript runs on V8 and rendering uses Chromium's pipeline. The engine is
designed to consume almost no CPU while a page is idle. On the other hand,
Chromium-based engines tend to use more memory than WebKit. Evaluate against
your own workload (see the
engine comparison).

Does it run on X11?

No. A Wayland session is required.

Where should I start?

Build and run the "After" code above by following
Building your application first, then move on
to replacing calls in your own app.

Related

• Building your application — the complete linking and resource walkthrough
• How do I…? — find the function by goal
• API index
• Engine comparison — detailed comparison with WebKitGTK and CEF

History