Author: BlinkGTK Project
Last updated: 2026-10-27 (BlinkGTK 1.2.5-build5 /
Chromium 156.0.8078.79)
This document is Chapter 9 (Environment Variables) of the API Reference Manual. Every environment variable BlinkGTK reads is listed here; a name that is not here is not used by BlinkGTK.
The variables are divided into three groups. Applications that embed BlinkGTK should rely only on the first group, "Publicly supported".
| Variable | Values | Default | Description |
|---|---|---|---|
BLINKGTK_GPU_MODE |
software / egl /
swiftshader |
software |
Rendering mode selection. software is recommended and
default. egl is the GPU path (experimental);
swiftshader is equivalent to software |
BLINKGTK_HEADLESS |
1 |
unset | Headless operation (no real display; for CI). Controls
--headless |
BLINKGTK_NO_SANDBOX |
1 / 0 |
unset | 1 = always disable. 0 = always keep it
enabled. Unset = decided automatically —
/proc/sys/user/max_user_namespaces is read, and the sandbox
is disabled if it is 0 or unreadable. Ask
blink_gtk_is_sandboxed() for the result |
BLINKGTK_EXTRA_SCHEMES |
comma-separated scheme names | unset | Registers your own URL schemes (e.g. ebook) as standard
schemes, treated like https. Used together with the handler
that loads your scheme (custom scheme loader) |
BLINKGTK_SCROLL_SPEED |
— | — | Deprecated. Setting it has no effect. Scroll distance is decided by fixed coefficients (measured 2026-09-15). The code still exists but is not present in any shipped binary |
BLINKGTK_DMABUF_PATH |
path | unset | dmabuf device path for egl mode |
BLINKGTK_FRAME_PNG_DIR |
directory path | unset | Destination for frame PNG dumps (verification use; only saved when set) |
BLINKGTK_FRAME_PNG_MAX |
integer | 0 |
Number of diagnostic frame PNGs to save. Default 0 = save none. Set a count only when you need the diagnostics |
BLINKGTK_DISABLE_SITE_ISOLATION |
1 |
unset | Disables per-site process isolation. This weakens protection. Isolation is the boundary that stops a compromised page on one site from reading another site's data; without it, documents from several sites share one process. On by default since v1.2.0-build8 — this variable exists as an escape hatch |
BLINKGTK_PRESENT_POLICY |
warm / warm-force |
unset | Stops the work of putting frames on screen (compositing, capture,
transfer) for a window nobody is watching. Layout and raster
keep running, so look-ahead is preserved. warm
applies only while the window is hidden; warm-force is
for testing only and always applies. On resume the
engine captures once unconditionally, so no stale frame is shown. While
stopped, a screenshot request
(blink_web_view_capture_screenshot_async() and similar)
still succeeds, and presentation stays stopped (1.2.3-build2 and later;
earlier versions failed after 2 seconds). Since 1.2.4-build3, the
capture on the software path returns, in most cases, the screen at the
time of the request and may finish without putting a frame on
screen |
BLINKGTK_LOG_LEVEL |
0 / 1 / 2 |
0 |
Diagnostic output volume: 0 everything, 1
much reduced, 2 nearly silent. Raise it if the logs
feel noisy |
BLINKGTK_DIAG_VERBOSE |
1 |
unset | Also emit per-frame diagnostics (suppressed by default) |
BLINKGTK_IM_MODULE |
gtk or a GTK input-module id |
unset | From v1.2.3. Chooses the input method. Unset (or
gtk) makes BlinkGTK pin nothing and leave the choice to GTK
(the text-input path on Wayland). Any other value (such as
ibus) is pinned on BlinkGTK's views. To get the
1.2.2 behaviour, set ibus. Query the configured
value with blink_gtk_get_im_module() |
GTK_IM_MODULE |
a GTK input-module id | — | From v1.2.3, it also affects BlinkGTK WebViews when
BLINKGTK_IM_MODULE is unset, because BlinkGTK follows GTK's
normal selection. If BLINKGTK_IM_MODULE pins an id, GTK 4's
gtk_im_multicontext_set_context_id() takes precedence over
this variable and it has no effect on WebViews. Up to 1.2.2 BlinkGTK
always pinned ibus and set this variable
process-wide from XMODIFIERS; 1.2.3 no
longer does |
BLINKGTK_A11Y |
1 |
unset | Enables accessibility. Exposes the page structure
over AT-SPI so that assistive technologies (Orca and the like) can read
the web content. By default Chromium does not build the accessibility
information for the page, so there is nothing to expose. Building it for
every page has a cost, so it is opened on request. Without it,
accessibility opens automatically when an assistive technology (Orca and
the like) connects (since 1.2.2-build4, including when the assistive
technology is started after the application). From 1.2.4 this also works
with at-spi2-core 2.61 or later (Fedora 45 and the like), and when an
assistive technology is started after launching with
BLINKGTK_A11Y=1. Set 1 where automatic
activation does not happen. The command-line switch
--force-renderer-accessibility does the same thing, but the
environment variable does not depend on how the program is launched |
BLINKGTK_UPDATE_CHECK |
1 |
unset (off) | Since 1.2.4. Tells you in two log lines, English
and Japanese
([BlinkGTK update] A newer version is available: ... /
[BlinkGTK update] 新しい版があります: ...), when a newer
version has been released. An application can also turn it on with
blink_gtk_set_update_check(TRUE) (call it before
blink_gtk_init()); even then the user can stop it with
BLINKGTK_UPDATE_CHECK=0 (the user setting wins).
Off by default — BlinkGTK is embedded in other
products, and it must not contact the network without the product user
knowing. Only with 1, it reads the release list of the
distribution repository (GitHub API, api.github.com) once,
5 seconds after startup. Attachments are not downloaded. It checks at
most once a day and keeps the result in
$XDG_CACHE_HOME/blinkgtk/update-check. Windows releases are
not mistaken for Linux ones. When the network is unavailable it says
nothing and does not delay startup |
BLINKGTK_SUBPROCESS_PATH |
Path to an executable, or 0 |
Unset (automatic) | Since 1.2.5. When BlinkGTK is used from a program
that does not link it directly, such as Python (PyGObject) or GJS,
BlinkGTK starts its child processes (the zygote and others) with
blinkgtk-subprocess, which is installed with BlinkGTK
(/usr/libexec/blinkgtk-0.1/blinkgtk-subprocess in the RPM
and DEB packages). The sandbox stays enabled. Up to 1.2.4, python3 or a
similar interpreter was started as the child process, so BlinkGTK could
not be started from Python. If you ship the file in a different place,
set its path here. 0 keeps the child process executable
unchanged (the 1.2.4 behavior). C applications do not need this: their
own executable serves as the child process |
BLINKGTK_WIN_GPU_PATH |
vulkan |
unset | Windows only, experimental (from BlinkGTK for Windows
1.2.4-build4). With the value vulkan, the result
of Chromium's GPU compositing is handed to GTK's Vulkan renderer without
reading it back to the CPU. This is what the site and the Windows
release announcements call "GPU path P4" (the only value you set is
vulkan). Disabled by default. Confirmed on one
Intel Iris Xe machine only. Not used on Linux |
BLINKGTK_NO_AUTO_SHUTDOWN |
1 |
unset (clean up automatically) | Windows only (from the next BlinkGTK for Windows release;
not in a released build). On Windows, BlinkGTK calls
blink_gtk_shutdown() automatically when
blink_gtk_run_main_loop() returns, so the process exits
soon after the window is closed. With 1, this automatic
cleanup is skipped. This is for applications that keep using BlinkGTK
after the main loop returns; such an application must call
blink_gtk_shutdown() itself before it exits. Calling
blink_gtk_shutdown() yourself is harmless: a second call
does nothing. Not used on Linux |
BLINKGTK_FOLLOW_GTK_THEME |
0 |
unset (follow the GTK theme) | From 1.2.5-build2. By default the page color scheme
(prefers-color-scheme, form controls, scrollbars) follows
whether the GTK theme is light or dark, and switching the theme while
the app runs switches the page without reloading it. With
0, pages are always light, as up to 1.2.5-build1. Use it in
apps whose HTML is not ready for dark. Pages that do not set
color-scheme keep a white background even without
0 |
BLINKGTK_NETWORK_IN_PROCESS |
1 |
unset (separate process) | From 1.2.5-build2. Runs networking inside the application process instead of in a separate process. Pages load sooner because a process is no longer started each time a page is opened. In exchange, if networking crashes, the application ends with it. By default networking runs in a separate process, so a crash ends only that process |
Use these when a problem appears and one of the fixes below may be involved: they turn off just that fix so you can check. If the symptom goes away, please report it with the version you use and the symptom.
| Variable | Effect when set (e.g. =0) | Related fix |
|---|---|---|
BLINKGTK_PUMP_LEGACY=1 |
Switches the main loop from the method that watches the Wayland connection (fd-watcher pump) back to the earlier method (g_idle pump) (CPU usage while idle increases) | Fix in 1.1.0: CPU usage of nearly one core while nothing was happening |
BLINKGTK_DEFER_ZYGOTE=0 |
Restores the earlier order in which startup first waits until the helper process that creates child processes (the zygote) is ready (startup becomes slower) | Improvement in 1.2.5-build2: faster startup (the window and the finished page load appear sooner) |
BLINKGTK_FAST_RENDER_NODE=0 |
Restores Chromium's original startup step that loads Mesa to check whether the GPU device (the render node under /dev/dri) is usable (startup becomes slower). Only matters on the software path (the default) | Improvement in 1.2.5-build2: faster startup (the finished page load appears sooner) |
BLINKGTK_VK_DRIVER_SELECT=0 |
Stops limiting the Vulkan drivers loaded at startup to the ones for
the GPUs present on this machine (startup becomes slower). If you set
the Vulkan loader's own variables (such as
VK_LOADER_DRIVERS_SELECT), BlinkGTK leaves them
unchanged |
Improvement in 1.2.5-build2: faster startup (the window appears sooner) |
BLINKGTK_PUMP_RESCUE=0 |
Disables the guarantee that wakes the main loop every 100 ms | Added in 1.1.0 together with the fix for the page staying blank (below) |
BLINKGTK_QUEUE_DRAW_TIMER=1 |
Since 1.2.4. Always runs the periodic redraw every 16 ms, as earlier
versions did. By default 1.2.4 does not run it for BlinkWebView, so a
static page is not redrawn over and over (lower CPU usage while idle).
=0 always stops it |
Change in 1.2.4: a static page is no longer redrawn every 16 ms |
BLINKGTK_T2_AUTO=0 |
Since 1.2.4. Stops automatically switching software rendering to T2
(a path that receives the composited result through shared memory
instead of capturing it) on a scale-1 display, and uses the same path as
earlier versions. By default 1.2.4 selects T2 at scale 1, which lowers
CPU usage on pages where only a small area changes. T2 is not used on
displays with a scale other than 1, and the original path is restored
when the window moves to one. BLINKGTK_USE_MOJO_IPC=0 does
the same |
Change in 1.2.4: T2 became the default on scale-1 displays |
BLINKGTK_CAPTURE_DAMAGE_GATE=0 |
Disables the mechanism that skips copying the screen (capture) when nothing has changed (capture damage gate) | Fix in 1.1.0: CPU usage while idle |
BLINKGTK_FORCE_SINGLE_THREADED=1 |
Reverts the renderer to single-threaded compositing (risk of rendering stalls) | |
BLINKGTK_120_INVAL_FALLBACK=0 |
Disables the fallback used when the area to redraw is computed as empty (invalidation fallback) | Fix in 1.1.0: right after a large font-size change, the page could stay blank |
BLINKGTK_EGL_AUTO_FALLBACK=0 |
Disable the automatic fallback to software when the GPU path is unusable (the window then stays blank) | |
BLINKGTK_EGL_AUTO_FALLBACK_MS=<ms> |
Wait before falling back (default 5000). Shortening it causes false fallbacks on machines with slow GPU startup | |
BLINKGTK_120_ACT_REDRAW=0 |
Disables the mechanism that asks for one more redraw when a new rendering result is activated (activation re-damage) | Fix in 1.1.0: right after a large font-size change, the page could stay blank |
BLINKGTK_120_CKB_REDRAW=0 |
Disables the mechanism that asks for a redraw when parts not yet drawn (checkerboard) remain | Backup measure for the fix in 1.1.0 (right after a large font-size change, the page could stay blank) |
BLINKGTK_EGL_FRACTIONAL=1 |
Opts in to fractional scaling in egl mode (experimental). From
1.2.4, pages on a 1.25 or 1.5 display are drawn at that fractional scale
(devicePixelRatio 1.25 / 1.5). In 1.2.3 and earlier (since
1.2.0-build3), the scale the engine adds automatically was rounded up to
an integer, so pages were drawn at 2 |
Opt-in since 1.1.0. Fixed in 1.2.4 to draw at the fractional scale |
BLINKGTK_EGL_RESIZE_BRIDGE=0 |
Disables the egl resize bridge | |
BLINKGTK_RUBY_RESERVE_EM=0.5 |
Restores the behaviour up to v1.2.0: subtract the ruby overhang (0.5em) from the column fragmentation width in multi-column layout. The subtraction reduces what fits in a column and can cost exactly one line | v1.2.1 change: the default became 0 (no subtraction) |
BLINKGTK_FRAME_COPY=1 |
Since 1.2.3-build4. In software rendering, go back to copying the pixels of every frame before handing them to GTK (the default now hands them over without a copy). For isolating display problems | |
BLINKGTK_EGL_FAKE_PRESENTATION=0 |
Since 1.2.4. In egl mode, do not send the "presented" notification, as before. With this, the renderer and browser memory keep growing while an animated page is shown (the behavior up to 1.2.3). For comparison only |
The following are internal variables for development and investigation. Listed for completeness only; their specifications are not published. Unwarranted and removable without notice.
| Area | Variables |
|---|---|
| Update notice tests | BLINKGTK_UPDATE_CHECK_URL (replaces the URL checked;
for the local server of check-update-notice.sh) |
| Investigating the page-stays-blank problem | BLINKGTK_120_CC_DIAG /
BLINKGTK_120_DISP_DIAG /
BLINKGTK_120_CLIP_DIAG / BLINKGTK_120_DIAG /
BLINKGTK_120_PAINT_KICK / BLINKGTK_120_FI_ROW1
(fault injection; verification only) /
BLINKGTK_120_TYPEB_FIX |
| Typesetting | BLINKGTK_VBREAK_P0 / BLINKGTK_TOC_P0 /
BLINKGTK_LAYOUT_DEBUG |
| EGL path | BLINKGTK_EGL_DIAG /
BLINKGTK_EGL_MANUAL_VIEWPORT /
BLINKGTK_EGL_BRIDGE_SETTLE_MS /
BLINKGTK_EGL_GTK4_NATIVE /
BLINKGTK_EGL_RECIPIENT_ALWAYS (prototype: always create the
EGL recipient surface, regardless of the active render path) |
| Output layer and compositing | BLINKGTK_USE_K2C / BLINKGTK_USE_MOJO_IPC /
BLINKGTK_USE_EGL_WIDGET /
BLINKGTK_T2_DELIVER_EMPTY (negative control: on T2, deliver
frames without waiting for the renderer's first frame) /
BLINKGTK_T2_DAMAGE (prototype, off by default: passes the
area Viz redrew on T2 to GTK, so only the changed area of the texture is
updated) / BLINKGTK_T2_DAMAGE_TEST_SHRINK (negative
control: shrinks the passed area by 1 px) /
BLINKGTK_T2_AUTO (0 stops automatically
selecting T2 on a scale-1 display; on by default since 1.2.4) /
BLINKGTK_TEST_PERMISSION_LOAD_DELAY_MS (testing only: delay
loading the stored permissions) /
BLINKGTK_USE_NEW_OUTPUT_DEVICE /
BLINKGTK_USE_FSVC / BLINKGTK_SW_SUBSURFACE /
BLINKGTK_REENABLE_ENDPAINT_HOOK /
BLINKGTK_AURA_SHOW_IMMEDIATE |
| Live render path switching | BLINKGTK_BLINKSHIFT_AUTOSWAP /
BLINKGTK_BLINKSHIFT_EGL_RECREATE /
BLINKGTK_BLINKSHIFT_NO_KICK |
| Tracing and measurement | BLINKGTK_GX_LOG (one line per event when the EGL
rendering result is handed to the screen:
BJGX <event> t=<ms> buf=<wl_buffer wire id> submit=<n>)
/ BLINKGTK_CAPTURE_TRACE / BLINKGTK_MOJO_TRACE
/ BLINKGTK_TRACE_PIXEL_SUPPLIER /
BLINKGTK_HARNESS_AUDIT / BLINKGTK_MINORI /
BLINKGTK_PROFILE_DIR /
BLINKGTK_RESIZE_FIT |
| Verification only | BLINKGTK_DELIVER_LOG_MAX (maximum lines of the log for
handing EGL rendering results to the screen; default 5. Lets you follow
which operation ran and which wl_buffer it used into the steady state
when nothing appears on screen) /
BLINKGTK_CONTENT_PROBE_MAX (extends measurement
only into steady state; the display decision still uses the
first 8 frames) / BLINKGTK_TEST_FORCE_FRACTIONAL /
BLINKGTK_TEST_GPU_COPYFROMSURFACE /
BLINKGTK_TEST_ALLOC_LOG /
BLINKGTK_TEST_GATE_FAKE_PRE (negative control: replaces the
reference value the check compares against) /
BLINKGTK_TEST_FOCUS_LOG /
BLINKGTK_TEST_SWITCH_PATH
(<path id>:<ms>) /
BLINKGTK_TEST_COMPOSITOR_RECREATE /
BLINKGTK_TEST_DISPOSE_QUIT_MS /
BLINKGTK_TEST_EXECV_RESTART /
BLINKGTK_TEST_OUTPUT_SWAP /
BLINKGTK_TEST_OUTPUT_SWAP_SKIP |
simple_browser) only — no effect in the
distributionThese have no effect on the library or on the sample
blinkgtk_browser that ships in the packages. Only
simple_browser, the demo used to develop BlinkGTK, reads
them, and simple_browser is not included in the
packages.
| Variable | Effect |
|---|---|
BLINKGTK_RESTART_ACTIVATION=0 |
Stops carrying the activation token across a restart (carrying it brings the new window to the front) |
BLINKGTK_RESTART_LINGER_MS=<ms> |
Restart by forking and letting the parent linger for this long. Defaults to 0 (disabled), which restarts via execv as before |
BLINKGTK_DEMO_SELECT_PATH=<id>@<ms>,... |
Testing only. Selects item <id> in the render
path list at the given number of milliseconds after startup (for example
egl@6000,software@12000). It goes through the same handling
as when a person picks from the list |
BLINKGTK_PERMISSION_ALLOW |
The demo auto-approves permission requests. The library itself denies by default |
BLINKGTK_INSPECTOR_DASH |
Opens the inspector dashboard |
BLINKGTK_TEST_SUITE /
BLINKGTK_TEST_CAPTURE |
Demo verification modes |
BLINKGTK_DEMO_NO_EBOOK /
BLINKGTK_DEMO_NO_JLREQ |
Disable the demo's EBOOK setting / JLReq typesetting at startup |
BLINKGTK_MUTTER_REACTIVATE /
BLINKGTK_DEBUG_ISSUE_84 |
For isolating window-raising behaviour |
BLINKGTK_CHROMIUM_VERSION |
Deprecated. It belonged to an internal demo that is not shipped. It has no effect in the distribution |
BLINKGTK_AUTO_RESIZE=<count> |
The demo resizes its own window this many times (for verifying resize behaviour). It does not disable resizing |
BLINKGTK_AUTO_FULLSCREEN=<count> |
The demo toggles fullscreen this many times, every 2.5 s, to produce a large single-step size change |
| Variable | Status |
|---|---|
BLINKGTK_KEEP_GPU_COMPOSITING=1 |
Do not disable GPU compositing even when starting in
software. Required if the rendering path is to be switched
at runtime. CPU use goes up (in our measurement, an
animating page over 20 seconds cost about 12% more; that is the ratio
for that machine and page, neither an upper bound nor a representative
value). Unsupported until switching the EGL path becomes public API |
BLINKGTK_ENABLE_THREADED_COMPOSITING |
Deprecated (threaded compositing is now ON by default; the old name has no effect) |
BLINKGTK_GPU_MODE selects and how to choose one