BlinkGTK Environment Variables Reference (Canonical Supported List)

Author: BlinkGTK Project
Last updated: 2026-08-01 (Chromium 151 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).

• Publicly supported — Stable API. Backward compatibility is maintained; changes are announced in release notes.
• Escape hatches — Troubleshooting switches that disable fixes/mechanisms which are ON by default. Do not set these in normal operation. Use them only to isolate problems, never as permanent configuration (they may be removed in future releases after notice).
• Internal diagnostics — For development and investigation. Unsupported and unwarranted; may change or disappear without notice. Embedders must not depend on them.

---

1. Publicly Supported Variables

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	unset	Disables the Chromium sandbox. For environments (e.g. containers) where the sandbox is unavailable
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	number (multiplier)	1.0	Wheel scroll speed multiplier
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	implementation default	Maximum number of frame PNGs to save

2. Escape Hatches (leave at defaults)

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_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

3. Internal Diagnostics (unsupported)

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

4. Deprecated

Variable	Status
BLINKGTK_ENABLE_THREADED_COMPOSITING	Deprecated (threaded compositing is now ON by default; the old name has no effect)

---

See also

• c-api-reference-en.md §BLINKGTK_GPU_MODE (to be consolidated into this reference)
• This file is the canonical source for Chapter 9 of the API Reference Manual (#121)