Author: BlinkGTK Project
Last updated: 2026-09-02 (BlinkGTK 1.2.2 / Chromium 153
baseline; canonical source for Chapter 9 of the API Reference Manual,
#121)
Environment variables interpreted by BlinkGTK are defined in three tiers. Embedders may only depend on tier 1 (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 additional custom URL schemes as standard schemes (e.g.
ebook). Used with the 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 |
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_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. Automatic
activation on assistive-technology connection is not implemented
yet (starting Orca alone does not enable it). The command-line
switch --force-renderer-accessibility does the same thing,
but the environment variable does not depend on how the program is
launched |
| Variable | Effect when set (e.g. =0) | Related |
|---|---|---|
BLINKGTK_PUMP_LEGACY=1 |
Disables the fd-watcher pump, reverting to the legacy g_idle pump (idle CPU increases) | #115 |
BLINKGTK_PUMP_RESCUE=0 |
Disables the pump wakeup guarantee (100 ms heartbeat) | #120 |
BLINKGTK_CAPTURE_DAMAGE_GATE=0 |
Disables the capture damage gate (frame-copy suppression while idle) | #115 |
BLINKGTK_FORCE_SINGLE_THREADED=1 |
Reverts the renderer to single-threaded compositing (risk of rendering stalls) | |
BLINKGTK_120_INVAL_FALLBACK=0 |
Disables the invalidation fallback (fix for persistent-blank) | #120 fixG |
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 activation re-damage (fix for persistent-blank) | #120 fixF |
BLINKGTK_120_CKB_REDRAW=0 |
Disables checkerboard re-damage (safety net) | #120 fixE |
BLINKGTK_EGL_FRACTIONAL=1 |
Opts in to fractional scaling in egl mode (experimental) | #117 |
BLINKGTK_EGL_RESIZE_BRIDGE=0 |
Disables the egl resize bridge |
The following are internal variables for development and investigation. Listed for completeness only; their specifications are not published. Unwarranted and removable without notice.
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_VBREAK_P0 /
BLINKGTK_TOC_P0 / BLINKGTK_LAYOUT_DEBUG /
BLINKGTK_RUBY_RESERVE_EM / BLINKGTK_EGL_DIAG /
BLINKGTK_EGL_MANUAL_VIEWPORT /
BLINKGTK_EGL_BRIDGE_SETTLE_MS /
BLINKGTK_EGL_GTK4_NATIVE /
BLINKGTK_TEST_FORCE_FRACTIONAL /
BLINKGTK_TEST_GPU_COPYFROMSURFACE /
BLINKGTK_USE_K2C / BLINKGTK_USE_MOJO_IPC /
BLINKGTK_USE_EGL_WIDGET /
BLINKGTK_USE_NEW_OUTPUT_DEVICE /
BLINKGTK_120_TYPEB_FIX /
BLINKGTK_REENABLE_ENDPAINT_HOOK /
BLINKGTK_HARNESS_AUDIT /
BLINKGTK_AURA_SHOW_IMMEDIATE /
BLINKGTK_USE_FSVC / BLINKGTK_SW_SUBSURFACE /
BLINKGTK_GX_LOG (one line per EGL delivery event:
BJGX <event> t=<ms> buf=<wl_buffer wire id> submit=<n>)
/ BLINKGTK_CAPTURE_TRACE / BLINKGTK_MOJO_TRACE
/ BLINKGTK_EGL_RECIPIENT_ALWAYS (prototype: always create
the EGL recipient surface, regardless of the active render path) /
BLINKGTK_DELIVER_LOG_MAX (maximum EGL delivery log lines;
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_ALLOC_LOG /
BLINKGTK_TEST_GATE_FAKE_PRE (negative control: substitutes
the gate's baseline) / BLINKGTK_TEST_FOCUS_LOG /
BLINKGTK_TEST_SWITCH_PATH
(<path id>:<ms> — switch render path
automatically) / BLINKGTK_BLINKSHIFT_AUTOSWAP /
BLINKGTK_BLINKSHIFT_EGL_RECREATE /
BLINKGTK_BLINKSHIFT_NO_KICK / BLINKGTK_MINORI
/ BLINKGTK_PROFILE_DIR / BLINKGTK_RESIZE_FIT /
BLINKGTK_TRACE_PIXEL_SUPPLIER /
BLINKGTK_TEST_COMPOSITOR_RECREATE /
BLINKGTK_TEST_DISPOSE_QUIT_MS /
BLINKGTK_TEST_EXECV_RESTART /
BLINKGTK_TEST_OUTPUT_SWAP /
BLINKGTK_TEST_OUTPUT_SWAP_SKIP
simple_browser) onlyThese have no effect on the library. They apply only when running the bundled demo.
| 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_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) |
c-api-reference-en.md §BLINKGTK_GPU_MODE (to be
consolidated into this reference)